GitHub workflows let you automate your software development life cycle processes directly within GitHub. You configure them to run based on an event in a repository, like a pull-request or a merge. When workflows are run, they pull what is in the repo onto a virtual machine (of your choice) and execute all the actions configured for it. The Services Change Report action uses the Lightstep Observability API to take a Snapshot immediately after a deployment (based on the GitHub SHA or snapshot query of your choice), stores it, and then pulls a previous Snapshot and compares the two for performance issues.

This action works best if your GitHub workflows identify the Git commit (SHA) for every running service in an environment. Downstream dependencies will only appear in a snapshot if multiple service(s) are released from the same tag/release.

You configure the workflow and the actions in it using a YAML file.

The workflow should have a step before the Services Change Report action that checks out the repository to a virtual machine.

Before you add the action to your workflow, you need to create a Lightstep-specific configuration file that provides your Lightstep Observability organization and product names.

Create the Lightstep YAML file

This file provides your Lightstep organization and project name.

  1. In the root directory of your repo, create a YAML file named .lightstep.yml

  2. Add the following to your file:

    1
2

     organization: <YOUR_ORGANIZATION_NAME>
 project: <YOUR_PROJECT_NAME>

    You can find your project name and organization name in Project settings and Account management.

Now you can add the Services Change Report action to your workflow.

Add the Services Change Report action to a GitHub workflow

In this step, we’ll add the Services Change Report action to a workflow for when the deployment_status_state GitHub event is successful.

  1. Open your workflow’s YAML file. If you don’t already have one, read GitHub’s docs to create one, or use the full example below.

    The Services Change Report action uses the ubuntu-latest GitHub Actions runner. Be sure that is configured for the runs-on property in the jobs section.
    If you don’t already have a step for checking out the repo, add that before the Snapshot step.

  2. Add a step for the Services Change Report action. The action for this step calls the Snapshots API endpoint to create a new snapshot. By using the GitHub SHA that you set as a resource attribute for the deployment marker in the previous step, you ensure that any changes that affect performance are attributed to this release.

    You need to have set a Lightstep API key for your account as a GitHub secret.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

     name: Lightstep Post-Deploy Check
 on:
   deployment_status:

 jobs:    
   postdeploy_check_job:
     runs-on: ubuntu-latest
     name: Compare Snapshots
     if: github.event.deployment_status.state == 'success'
     steps:  
       - name: Checkout
         uses: actions/checkout@v2

       - name: 📸 Take Lightstep Snapshot
         id: lightstep-take-snapshot
         uses: lightstep/lightstep-action-snapshot@v2
         with:
           lightstep_api_key: ${{ secrets.LIGHTSTEP_API_TOKEN }}
           # Recommended to use a query based on SHA (or version) so telemetry always 
           # points to the code that's being deployed in this workflow
           lightstep_snapshot_query: '"github.sha" IN ("${{ github.sha }}")'

  3. The action needs to wait for the Snapshot request to complete and then it stores the Snapshot to a temporary directory.

    1
2
3
4
5
6
7
8
9

     - name: Wait for Snapshot to Complete
   run: sleep 240

 - name: Cache Snapshots
   id: cache-snapshots
   uses: actions/cache@v2
   with:
     path: /tmp/lightstep
     key: ${{ steps.lightstep-take-snapshot.outputs.lightstep_project }}-snapshot

  4. To compare this snapshot with one before the deploy, create a step that queries the Lightstep Observability API for another Snapshot. You can use a wildcard (*) to retrieve the most recent one.
    Optionally, if you only want the snapshot to query specific services, you can use the lightstep_service_filter to do that. In this example, we’ll query on the web, iOS, android, and inventory services.
    Lastly, you reference the Snapshot taken at the beginning of the workflow for comparison.

    You need to have set GitHub token as a secret

    1
2
3
4
5
6
7
8
9
10
11

     - name: Compare Snapshots
   id: lightstep-snapshot
   uses: lightstep/lightstep-action-snapshot@v2
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   with:
     lightstep_api_key: ${{ secrets.LIGHTSTEP_API_TOKEN }}
     lightstep_snapshot_compare_id: '*'
     # lightstep_service_filter is optional.
     lightstep_service_filter: web,iOS,android,inventory
     lightstep_snapshot_id: ${{ steps.lightstep-take-snapshot.outputs.lightstep_snapshot_id }}

Here’s a full example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

name: Lightstep Post-Deploy Check
on:
  deployment_status:

jobs:    
  postdeploy_check_job:
    runs-on: ubuntu-latest
    name: Compare Snapshots
    if: github.event.deployment_status.state == 'success'
    steps:  
      - name: Checkout
        uses: actions/checkout@v2

      - name: 📸 Take Lightstep Snapshot
        id: lightstep-take-snapshot
        uses: lightstep/lightstep-action-snapshot@v2
        with:
          lightstep_api_key: ${{ secrets.LIGHTSTEP_API_TOKEN }}
          # Recommended to use a query based on SHA (or version) so telemetry always 
          # points to the code that's being deployed in this workflow
          lightstep_snapshot_query: '"github.sha" IN ("${{ github.sha }}")'

      - name: Wait for Snapshot to Complete
        run: sleep 240

      - name: Cache Snapshots
        id: cache-snapshots
        uses: actions/cache@v2
        with:
          path: /tmp/lightstep
          key: ${{ steps.lightstep-take-snapshot.outputs.lightstep_project }}-snapshots

      - name: Compare Snapshots
        id: lightstep-snapshot
        uses: lightstep/lightstep-action-snapshot@v2
        env:
          ROLLBAR_API_TOKEN: ${{ secrets.ROLLBAR_API_TOKEN }}
          PAGERDUTY_API_TOKEN: ${{ secrets.PAGERDUTY_API_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          lightstep_api_key: ${{ secrets.LIGHTSTEP_API_TOKEN }}
          # Infer a recent snapshot to compare with using the API:
          # '*' uses most recent available (per project or repo tag if exists)
          lightstep_snapshot_compare_id: '*'
          # If your project has lots of services, you can filter the output
          # to a subset. This is useful for monorepos.
          lightstep_service_filter: web,iOS,android,inventory
          lightstep_snapshot_id: ${{ steps.lightstep-take-snapshot.outputs.lightstep_snapshot_id }}

Your workflow is now configured to work whenever the deployment_status_state GitHub event is successful. The Services Change Report is added to the PR. Services Change Report

Each service in the report is a link to the Service Health view for that service, where you can see its current performance. Service Health view

The Downstream Dependencies links show the health view for any downstream services. Service Health view

Downstream dependencies will only appear in a snapshot if multiple service(s) are released from the same tag/release.

Service Operations links to the Explorer view loaded with Snapshot data for that service. Explorer view for operation

Under What caused that change? are links to the Explorer view for each of the Snapshots that were taken. Additional links allow you to view the Trace Analysis table grouped by either the GitHub SHA or by Rollbar error. Explorer view

In the next step, you’ll learn how to use the Service Change Report action to take a Snapshot when a specific label is applied to a GitHub issue.

What did we learn?

  • Each action requires a YAML file stored at the root directory to provide project-specific information.
  • Actions are embedded as steps into a GitHub workflow.