The Services Change Report action determines the health of the system when a new version is released and compares it to the health before the release using Snapshots and deployment markers.

Deployment markers signify that the version of a service has changed. They rely on version attributes (aka “release tags”) that you add to your service instrumentation. You register that attribute with Lightstep so that it can collect that attribute data from your spans. When Lightstep finds a change in its value, it creates a marker based on the timestamp of the span.

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.

Instrument for Deployment Markers

Add an attribute (known as a tag in OpenTracing) with values to your services that can be used to report version information.

For example, you might create an attribute named service.version with values equal to the Git commit hash of the current version.

For optimal discoverability in Lightstep, we recommend that you use the Git commit hash or a Docker container tag, rather than semantic versions.

See the individual language Quick Start topics for instructions on how to create attributes.

Set the SHA as an environment variable

If you’re using a Docker container, you can use the Git SHA provided by the CI system as the service.version attribute. Here’s a Skaffold configuration file that builds a Docker container using the GITHUB_SHA environment variable:

1
2
3
4
5
- image: productcatalogservice
  context: src/productcatalogservice
  docker:
    buildArgs:
      SERVICE_VERSION: "{{.GITHUB_SHA}}"

Expandable end

The Instrumentation Quality Score checks for version attributes on your services.

Register the Attribute with Lightstep

Deployment markers are project-specific. You need to register the version attributes with all projects that should use them.

  1. Click Settings to open your project’s settings page.
  2. On the Project Settings page, scroll down to Deployment version settings.
  3. Click into the field and start typing the attribute name. Select the version attribute from the list.

The attribute now displays as the Version Attribute.

You can use multiple attributes to collect deployment information. As long as they are all registered, Lightstep creates markers when a change in value is detected.


What Did We Learn?

  • Lightstep uses deployment markers to keep track of system health across deployments.
  • Deployment markers use your instrumentation attributes to understand new versions.