Create Workflow Links for On-Call Teams

Often, the owner of an issue needs to jump between different tools, synthesize information from multiple sources, and notify other people quickly when triaging an issue. Workflow Links allow you to do this all from within Lightstep.

Workflow Links display on the Trace view and can be links to anything with a valid URL. Even better, the URLs can use variables so that values from the trace you’re viewing can be inserted into the URL.

For example, you can create a link to logs from the time when an issue occurred, using the timestamp on the span. Or you can have a link to your Playbook’s instructions based on the error code on the span.

In this example, let’s create a Workflow Link to the Playbook page for error codes.

1. Like many other features in Lightstep, Workflow Links can be created based on attribute values. In this example, you’d create a span and set an error.code attribute in your code where you handle the error.

1
2
3
4
5
6
  Span span = tracer.spanBuilder("/project/:project-id/list") // operation named after the route
                 .setSpanKind(Span.Kind.CLIENT) // tag the span as a service boundary
                 .startSpan();

  span.setAttribute("error.code", "429");
  span.end()

Now that the attribute is available, you can use it to build your Workflow Link.

1. To create a link that goes to the playbook page for an error code, we’ll start by selecting a span that uses the error.code attribute. When you click the Workflow Links tab in the panel, the Workflow Links applicable to that span display.

2. Click the New button to open the Create Workflow Link dialog.

3. Select Custom for the template (Lightstep offers a number of different templates to help create links). For the URL, enter the URL to any playbook page for an error code (we’ll replace it with a variable in the next step). Because we used the error.code attribute in the instrumentation, and because we have a wiki page for each code, instead of creating a static link for each code, we can replace the code number with the error.code variable, and the link will resolve to the correct page for the error on the span.

4. In the URL, change /Status+429+Error+Code+Playbook to /Status+{{error.code}}+Error+Code+Playbook so the link will resolve to the error code found on the span.

   Note that the active link in the dialog doesn’t change because Lightstep has already resolved the error.code variable to 429.

5. Now we need to tell Lightstep when to display the link. Because we want it to display for all error codes, we can use the value null to say “always”.
   For Step 3, enter:

   1
   2
   3
     {
    "error.code": null
     }
   

   This tells Lightstep to display the link whenever any error code is on the span.

6. Give it a name. We can use variables here too.

   If you’re unsure about what variable to use for any of the entries, click + Variable to view a list of all attributes on the current span.

7. Click Create Link. The link now displays for the span.

8. Click the link to navigate to the Playbook.

Be sure to check out our Workflow Links Cookbook! It has lots of templates to get you started.

What Did We Learn?

• You can create links in Lightstep to external apps and sites, keeping the context of the span you’re interested in.
• Workflow Links can use variables in the URLs, definitions, and names, taking values directly from the span.
• Lightstep has several Workflow Link templates and a cookbook to help create more complex links.