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.
-
In the root directory of your repo, create a YAML file named
.lightstep.yml
-
Add the following to your file:
1 2
organization: <YOUR_ORGANIZATION_NAME> project: <YOUR_PROJECT_NAME>
You can find your
project
name andorganization
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.
-
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 theruns-on
property in thejobs
section.
If you don’t already have a step for checking out the repo, add that before the Snapshot step. -
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 }}")'
-
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
-
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 thelightstep_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.
Each service in the report is a link to the Service Health view for that service, where you can see its current performance.
The Downstream Dependencies links show the health view for any downstream services.
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.
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.
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.