LightStep

LightStep Documentation

Welcome to the LightStep developer hub. You'll find comprehensive guides and documentation to help you start working with LightStep as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Create and Manage Workflow Links

You can create and edit Workflow Links from either the Trace View page or the Project Settings page.

Creating and editing links from the Trace View page allows you to experiment with link definitions on real span data and is the recommended approach.

Create Workflow Links from the Trace View page

Create Workflow Links from the Trace View page

The Project Settings page allows you to view all your Workflow Links in one place. You can create, copy, edit, and delete links from the Manage Links area.

Manage Workflow Links from the Project Settings page

Manage Workflow Links from the Project Settings page

Workflow links are project specific

If you have more than one project in LightStep, you need to create separate links for each.

Create Workflow Links

Any user with Admin or Member permissions can create, edit, and delete links.

To create a Workflow Link:

  1. On the Trace View page, click Create Link.

OR
Click Settings in the left navigation menu to open the Project Settings page.
In the Workflow Links area, click Create Link.

You can use one of the pre-built templates or you can create your own custom link.

Need more examples?

The templates are taken directly from the Workflow Links Cookbook and you can find even more examples there.

  1. To use a template, select the template from Step 1 in the dialog.

LightStep populates the fields with content from the template. You need to replace certain variables with your own. Click into an existing variable and click + Variable to choose one.

Read more about the template in the Workflow Links Cookbook to understand what to change.

When creating the link from the Trace View page, LightStep dynamically generates the link below the URL field so that you can test it. It also generates the link text below the name field, where you can test it.

If the link will not display for the span currently selected on the page, a warning displays.

  1. To create your own link, in the Create Link dialog, choose Custom for Step 1.
  • Enter a URL in the URL field.
    The URL can include variables you choose by clicking + Variable.

LightStep escapes the HTML, so you don't have to. As you type in a value, LightStep displays the link, allowing you to test it immediately.

Using variables?

Variables can be from the list of LightStep variables or your own span tags.

  • In the Rules box, enter JSON for your rule(s).
    Rules are written as a JSON object with tag/value pairs. Values can be the following:
    • null: The link will be displayed when that tag is present on the span, regardless of its value.
    • An array: The link will be displayed when the tag has one of the listed values. Even if you want only a single value, you still need to use array syntax.

Want the link to display for every span?

If you want a link to always display, no matter what, set the rule to {“$service”: null}, as every span has a service associated with it.

Values in an array are evaluated with a logical OR operator. The values between each rule are evaluated with a logical AND operator.

To help ensure you enter correct values, LightStep displays a warning if the value you entered will not display for the span currently selected.

This error only displays when creating links from the Trace View page, when you have a span selected.

Here’s an example of a rule that displays the link for every service, in any cluster, whose GCP Zone is us-centrall-f or us-east1.

{
   "$service": null,
   "MY_GCP_ZONE": ["us-central1-f", "us-east1"],
   "MY_GCP_CLUSTER": null,
}

You can also use NOT (!) in your rule. For example, if you do not want the above link to display for the api service, you might use this:

{
  "!$service”: ["api"],
  "MY_GCP_ZONE": ["us-central1-f", "us-east1"],
  "MY_GCP_CLUSTER": null,
}
  • Enter the text to display for the link in the Name field.
    Names can include variables (using mustache {{}} syntax). The limit is 64 characters. As you enter a value, LightStep shows how the link text will display. You can test the link by clicking it.

The Name + URL combination must be unique.
LightStep automatically encodes all URLs.

Why only on the Trace View page?

You can only test your links when creating them from the Trace View page because LightStep needs the context of the span to resolve variables that may be in the Name or URL.

  1. Click Create Link.
    Your link now appears in the list of links on the Project Settings page and, when the rule validates to true, on the Trace View page.

Don't see your link?

If your link doesn't display for a span, it's likely because the span doesn't contain the tags in your rule, or LightStep could not resolve the variables from the metadata in the span.

Manage Workflow Links

You can edit existing links from either the Trace View page or the Project Settings page. You can only copy and delete links from the Project Settings page. That page also shows when the link was last clicked, who it was created by, and when it was last edited.

Edit Workflow Links

  1. From the Links area of the Trace View page, click the pencil icon for the link to edit.

OR
From the Manage Links area of the Project Settings page, find the link to edit, then click the More Options (vertical ellipsis) button. Choose Edit to open the Edit Link dialog.

  1. Change any of the fields as needed. Remember that the Name + URL combination must remain unique for the project.

Clone Workflow Links

You can clone Workflow Links only from the Project Settings page.

  1. From the Manage Links area of the Project Settings page, find the link to clone, then click the More Options button and choose Clone.
    The Clone Link dialog opens, populated with the name, URL, and rules from the source link.
  1. You MUST change at least the Name or URL before saving the new link definition.

  2. Click Clone Link.
    The new link displays in the list of Workflow Links.

Delete Workflow Links

You can delete Workflow Links only from the Project Settings page.

  1. From the Manage Links area of the Project Settings page, find the link to edit, then click the More Options button.

  2. Choose Delete.

Want to create Workflow Links using our API?

You can also create and manage links using the LightStep public API.


What's Next

Check out these topics to help you create your links:

Using Variables in Workflow Links
Workflow Links Cookbook
Create Links to Important Information

Create and Manage Workflow Links


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.