You can use attributes from a service’s span data to display deployment markers in your charts in dashboards, notebooks, alerts, and Change Intelligence. The markers display at the time a service started to deploy. These markers allow you to quickly correlate a deployment with a change in performance. Hover over a marker to see the deployed service, along with the time the deployment started and the new version number. You can turn deployment markers on and off using the toggle. Deployment marker

Deployment markers rely on version attributes added to your service instrumentation. Once they are in place, you register that attribute on the Project Settings page. When Lightstep detects a change to the value, it creates a marker based on the timestamp of the span.

To use deployment markers, you need to:

Note the following:

  • Deployment markers rely on span data from services, so you must filter metric queries to a service(s) for the markers to display.
  • Each chart can display markers for up to 20 services. If a query returns more than 20 services with deployments in the chart’s time period, the chart won’t display markers.
  • Deployment markers can only display for data within your data retention period.

Instrument for deployment markers

Add an attribute to your service instrumentation to hold 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’s value 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 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. Version attribute

The attribute now displays as the Version Attribute. 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.