Getting started with Lightstep is easy! Sign up for a free account, instrument your services and libraries using our OpenTelemetry Launchers, learn how our Satellites capture and analyze 100% of the telemetry data and then view that data in Lightstep!

If you prefer a tutorial where you can actually work in a Lightstep project to get started, checkout our Learning Path!

Sign Up for a Free Account

Lightstep offers a free Community Tier account. If you don’t already have an account, you can sign up here.

If you company already has an account, click Join an existing team.

Instrument Your Services

Now it’s time to get data from your app into Lightstep. Lightstep supports OpenTelemetry to provide a way to get telemetry data (traces, logs, and metrics) from your app as requests travel through its many services and other infrastructure.

If you’ve never instrumented for observability, read Understand Distributed Tracing for some background knowledge.

Lightstep provides Launchers that install OpenTelemetry and capture telemetry from popular libraries and frameworks already installed in your system, with only one line of code needed. This type of instrumentation provides observability into a request as it travels from service to service.

OpenTelemetry (currently in Beta, with GA expected in November 2020) is the unified initiative that takes the best of both OpenTracing and OpenCensus forward. Think of OpenTelemetry as the next evolution of OpenTracing and OpenCensus.

To install the launchers, you need to configure them to communicate with the Lightstep Satellites.

Understand Lightstep Satellites

Lightstep uses Satellites to collect 100% of the performance data that your tracing instrumentation generates. Satellites collect telemetry data generated by instrumented clients and servers, and then process and temporarily store that data during trace assembly. The Hypothesis Engine (the remote SaaS component) queries the Satellites, records aggregate information about the spans, directs the trace assembly process, and then stores traces durably, all for display in the Lightstep UI.

Learn more about Satellites.

Satellites communicate with the instrumentation using an access token. Access tokens are project specific. You’ll need this access token when you install the launcher.

Configure OpenTelemetry

Launchers are available in Java, Node.js, Python, and Go.

If you’re using another language, you can still get started quickly!

Configure OpenTelemetry with the name of the service that you’d like to report tracing data from, an access token, and optionally the satellite endpoint. The variables that you set depend on the type of Satellite you’re using.

Unless your company already has on-premise Satellites, use the Public Satellites for this quick start.

Start tabs

Public Satellites

1
2
export LS_SERVICE_NAME=your_service_name
export LS_ACCESS_TOKEN=your_access_token

On-Premise Satellites

1
2
3
4
5
6
7
8
9
export LS_SERVICE_NAME=your_service_name
# The access token can be omitted for satellites running in single-project mode.
export LS_ACCESS_TOKEN=your_access_token
# The span endpoint defaults to ingest.lightstep.com:443 for all languages except Node.js.
# Node.js sends data over HTTP so the path must be included in the endpoint:
# https://ingest.lightstep.com:443/api/v2/otel/trace
export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT=your_satellite_endpoint
# If your satellites don't have TLS enabled, uncomment the following line.
# export OTEL_EXPORTER_OTLP_SPAN_INSECURE=true

Developer Mode

1
2
3
4
5
export LS_SERVICE_NAME=your_service_name
# For Node.js, instead use:
# export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT="http://localhost:8360/api/v2/otel/trace"
export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT="localhost:8360"
export OTEL_EXPORTER_OTLP_SPAN_INSECURE=true

End code tabs

Install OpenTelemetry

Start by installing the Lightstep OpenTelemetry launcher for your language. Lightstep’s launchers package all of the necessary OpenTelemetry dependencies with a configuration layer to ease setup.

Start tabs

Java

1
2
3
4
# Install the OpenTelemetry Java Agent
curl -L "https://github.com/lightstep/otel-launcher-java/releases/download/0.8.0/lightstep-opentelemetry-javaagent-0.8.0.jar" > lightstep-opentelemetry-javaagent-0.8.0.jar
# Run your application with the agent
java -javaagent:path/to/lightstep-opentelemetry-javaagent-0.8.0.jar -jar myapp.jar

Node.js

1
2
3
4
5
6
7
8
9
10
11
// In a shell, run:
// $ npm install lightstep-opentelemetry-launcher-node --save

// In your application code:
const { lightstep, opentelemetry } = require("lightstep-opentelemetry-launcher-node");
      
lightstep.configureOpenTelemetry().start().then(() => {
  // All of your application code and any imports that should
  // leverage OpenTelemetry instrumentation must go here; e.g.,
  // const express = require('express');
});

Python

1
2
3
4
5
6
7
8
9
# This install requires gcc and gcc-c++, which you may need to install if you're
# running a slim version of Linux (e.g., CentOS):
# yum -y install python3-devel
# yum -y install gcc-c++
pip3 install opentelemetry-launcher
# Detect installed libraries and install relevant instrumentation.
opentelemetry-bootstrap -a install
# Run your application
opentelemetry-instrument python3 your_app.py

Go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// In a shell, run:
// $ go get 'github.com/lightstep/otel-launcher-go/launcher'

// In your application code:
import (
   "context"
   "github.com/lightstep/otel-launcher-go/launcher"
   "go.opentelemetry.io/otel/api/global"
)

otel := launcher.ConfigureOpentelemetry()
defer otel.Shutdown()

tracer := global.Tracer("example")
_, span := tracer.Start(context.Background(), "main")
defer span.End()

End code tabs

Now that your service is instrumented, go ahead and run it to see the data in Lightstep!

Not only can Lightstep visualize your data to help you resolve issues quickly and improve performance, but it can also measure the quality of your instrumentation.

See Your Instrumentation Quality

When you use the Launchers for instrumentation, you get observability into a request as it travels from service to service. Adding instrumention to the interior of your services provides observability into the operations within the service. Lightstep helps you out with that by analyzing your instrumentation and showing how you can improve it to make Lightstep work even better for you.Instrumentation Quality view

With that analysis, you can now head over to our OpenTelemetry docs to learn how to add the instrumentation you need.

See Your Data in Lightstep

With your service running, you can immediately see span and trace data in the Explorer view.Explorer view

More about Explorer

When you hear that a particular service is slow, or there’s a spike in errors, or a particular customer is having an issue, your first action is to see real-time data regarding the issue. Lightstep’s Explorer view allows you to query all span data currently in the Satellites to see what’s going on.

Explorer consists of four main components. Each of these components provides a different view into the data returned by your query:

  • Query: Allows you to query on all span data currently in the Satellites recall window. Every query you make is saved as a Snapshot, meaning you can revisit the query made at this point in time, any time in the future, and see the data just as it was. Results from the query are shown in the Latency Histogram, the Trace Analysis table, and the Service diagram.

  • Latency histogram: Shows the distribution of spans over latency periods. Spans are shown in latency buckets represented by the blue lines. Longer blue lines mean there are more spans in that latency bucket. Lines towards the left have lower latency and towards the right, higher latency.

  • Trace Analysis table: Shows data for spans matching your query. By default, you can see the service, operation, latency, and start time for each span. Click a span to view it in the context of the trace.

  • Correlations panel: For latency, shows services, operations, and attributes that are correlated with the latency you are seeing in your results. That is, they appear more often in spans that are experiencing higher latency. For errors, shows attributes that are more often on spans that have errors. The panel can show both positive and negative correlations, allowing you to drill down into attributes that may be contributing to latency, as well as ruling out ones that are not. Find out more about Correlations here.

  • Service diagram: Depicts the service based on your query in relation to all its dependencies and possible code paths, both upstream and downstream. Areas of latency (yellow) and errors (red) are shown. Learn more about the Service diagram here.

Using these tools, it’s possible to quickly form and validate hypotheses around the current issue.

Learn more about Explorer.

Expandable end

Click on a row in the table (each row shows data from spans currently in the Satellite) to view a trace.Trace view

More about the Trace view

You use the Trace view to see a full trace from beginning to end of a request. The Trace view shows you a flame graph of the full trace (each service a different color), and below that, each span is shown in a hierarchy, allowing you to see the parent-child relationship of all the spans in the trace. Errors are shown in red.

Clicking a span shows details in the right panel, based on the span’s metadata. Whenever you view a trace in Lightstep, it’s persisted for the length of your Data Retention policy so it can be bookmarked, shared, and reviewed by your team at any time. The selected span is part of the URL, so it will remain selected when the URL is visited.

Learn more about traces.

Expandable end

Once the Satellites and the Hypothesis engine have had time to capture and analyze data, see how to you can use Lightstep for root cause analysis, deployment monitoring, and tracking your SLAs and SLOs.