What are Streams and Conditions?

The Pre-Deploy action relies on conditions on your Streams to determine if there are currently any issues in your system before you deploy. So you need to have those conditions and Streams set up before using the action.

Streams

Streams provide a time-series chart based on a query. You can query on a service, operation, and attributes. The chart shows you the latency, error rate, and operation rate for a time range, using a scatter plot to chart exemplar traces. Stream view Once you create a Stream, your Lightstep Satellites collect and persist the span data that matches your query.

Conditions

Conditions are thresholds you set on a Stream that when crossed, trigger an alert. An example might be if latency for a stream in the 99th percentile reaches 100ms for over 2 minutes. For the Pre-Deploy action, you need to create conditions for anything you want to be alerted about before you commit a pull request.

If you already have Streams and conditions, then you can skip to Step 2

Create a Stream

For this learning path, you’ll create one Stream. Remember for the action to be valuable, you’ll need to create Streams for anything that should keep you from deploying.

  1. Click Streams from the navigation bar.

  2. Click Create Stream.

  3. Enter a query to base your Stream on and click Run. Lightstep runs the query and returns example spans.

    Learn how to run a query

    To run a query using the Query Builder:
    Click into the search bar to open the Query Builder. You can build queries for services, operations, and attributes. Use IN or NOT IN to build the query. When you click into the Service or Operation field, Lightstep displays valid values.
    When you add multiple values to the Operation field, spans that match either value (OR operation) are returned.
    Learn more about running queries
    Supported query keys
    Query multiple keys and values

  4. If the results are satisfactory, click Create stream. The Stream is added to the list of Streams. By default, the Stream’s name is the query. You can rename it.

  5. To view the Stream, click VIEW STREAM in the banner or click its name in the list.

Lightstep starts collecting data for Streams once you create them, so when you create a Stream, it will initially be blank.

Create a Condition

Now you’ll create a condition that the action will use to determine if it’s safe to deploy.

  1. On the Stream you just created, click Create Conditions.

  2. Enter the following:

    • Signal: Select the metric Lightstep should analyze for this condition. Choose from Latency, Operation rate, or Error percentage.
    • Name: Enter a name for this condition.
    • Threshold: Create a condition for the metric that should trigger the alert. Configuration for the threshold depends on the signal you chose.
      • Latency: Lightstep analyzes the latency in units of time (m, s, ms, for microseconds put a number < 1ms) for a certain percentile bucket, and determines if the latency during the evaluation window is above or below the threshold.
      • Error Percentage: Lightstep checks every ingested span for the presence of the OpenTelemetry error attribute. The error percentage signal is the percentage of spans in a Stream population that contain an error. Lightstep can create an alert if the error percentage is above or below the threshold.
      • Operation Rate: Lightstep collects basic throughput information about Stream operations and determines if the rate is above or below that threshold.
    • Evaluation Window: The period of time during which you want Lightstep to perform the threshold calculations to determine if an alert should be created. This can be thought of as a moving time frame, trailing the current point in time, during which relative percentages are calculated for signals. Allowed units include: d (days), h (hours), m (minutes). The minimum value is 2 minutes.

    Higher values can be useful if you’d like to “smooth” out the data to avoid alerts during brief metric spikes.

You don’t have to create a destination or a rule because you won’t be using this condition to trigger an alert in a third-party app. You can use this same condition to do that if you want.


What Did We Learn?

  • Streams proactively collect span data based on their query. They report on latency, error rate, and operation rate.
  • Conditions set thresholds on a Stream that when crossed, provide a trigger. For the Pre-Deploy action, they let you know that it may not be safe to commit your pull request.