When you implement an attribute to display versions of your service, a deployment marker displays at the time the deployment occurred. In the example below, a deploy of the inventory service occurred at around 12:40 pm. Hover over the marker in the larger charts to view details. These markers allow you to quickly correlate deployment with a possible regression.

When you have multiple versions in a time window, you can view the performance of each deployed version. For example, in this image, multiple versions have been deployed. Hover over the chart to see the percentage of traffic in each version.

This feature requires a Satellite upgrade to the March 2020 release.

For more information about how deployment markers can be used during root cause analysis, see Monitor Deployments.

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

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.

Using GitLab or GitHub?

If you’re using GitLab or GitHub for your project, you can use a Git SHA provided by the CI system as the service.version attribute so you can easily connect your traces with specific commits of code. Here’s an example from a Skaffold configuration file used to build services for a Docker container:

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

For GitHub, here’s a similar 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 Settings.
  3. Click the + icon. A dropdown shows all attributes found in your instrumentation. Select the version attribute from the list.

The attribute now displays as the Version Attribute.