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 Observability so that it can collect that attribute data from your spans. When Lightstep Observability 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 Observability, 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:

- image: productcatalogservice
  context: src/productcatalogservice

Expandable end

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

Register the attribute with Lightstep Observability

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

  1. Click Project settings to open your project’s settings page.
  2. In Project settings, click Deployment versions.
  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 Observability creates markers when a change in value is detected.

What did we learn?

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