Getting started with Lightstep is easy! You can sign up for a free account, instrument your services to send data to your project, and then watch that data come in. But first, to get a good understanding of what Lightstep can do, play around in the Sandbox!

Play in the Sandbox!

Lightstep offers a fully interactive demo environment where you can see how Lightstep can help you investigate and solve real-world performance issues in deep, distributed systems. With a number of different scenarios to choose from, you can quickly see how easy and informative Lightstep can be.

To play in the Sandbox, visit https://app.lightstep.com/play and choose one of the scenarios.Lightstep Sandobx scenarios.

The interactive tutorial guides you through real-world examples of using Lightstep in your daily workflow.Lightstep Sandbox tutorial

Once you’re done playing click Start a Free Trial to set up an account.

Sign in to Lightstep

Access the Lightstep UI from https://app.lightstep.com or click the Log in to Lightstep button at the top of this page.

Create a User Account

When you sign up with Lightstep, your user account is associated with an organization, normally your company’s name. An organization in Lightstep can have many users and projects, reflecting the different environments that your services run in. You can choose to create a new organization if you’re the first in your company to join Lightstep, or you can ask to join an existing organization.

Once the first account for an organization is created, two default projects are created; one for development and one for production. You can use one of these or create your own.Lightstep start page

Join Lightstep as the First User

If you’re the first person in your organization to join, enter your work email, full name, and an organization name (usually the name of your company). Complete the reCAPTCHA form and accept the terms.Lightstep sign up form

Once your account is created, you can add users. If your plan allows it, you can set up your organization to be whitelisted so that anyone using the whitelisted domain can log in and create their user account. Or if your company uses Google Apps for Work teams, you can whitelist the Lightstep domain with Google to allow automatic sign in.

Join an Existing Organization

If someone at your company already created an organization, you can ask to join the existing team, or if your company uses Google Apps for Work teams and has whitelisted the Lightstep domain, you can create an account using your Google account information.

To join an existing team:
On the signup form, click Join an existing team.Lightstep signup form Enter your work email and the admin of your Lightstep organization will be prompted to create you as a user. You’ll receive an email with login information.

To sign up using Google:
On the signup form, click Sign up with Google.Lightstep signup form

If your Lightstep admin has whitelisted your company’s domain, click the SAML SSO tab and enter your email address.Lightstep sign-in form

If your Lightstep admin has integrated Lightstep with Google, click Sign in with Google.Lightstep signin form

Configure Lightstep Satellites

Lightstep uses Satellites to collect 100% of the performance data that your tracing instrumentation generates. Satellites collect spans 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 Lightstep’s architecture.

Lightstep does not assemble every trace from your instrumentation. From the 100% of spans collected, only traces that match Streams or serve as examples of application errors, high latency, or other interesting events are assembled.

Lightstep offers three Satellite types, used at different times during the development lifecycle:

  • Local Developer Mode Satellite installed on your machine: Used when developing a single service.
  • Public shared Satellite pool: Used in non-production environments to see performance throughout your system. Because they are in the cloud and shared between organizations, they do not have the performance or security needed for production environments.
  • On-premise Satellite pool: Installed and run in your environment. You maintain and tune these to suit your application’s needs.

Learn more about Satellites and how to configure them here

Satellites communicate with the tracers in your instrumentation using an access token. Access tokens are project specific. You’ll need this access token when you implement your instrumentation.

Instrument Your Services

Now that you have an account and projects, it’s time to get data from your app into Lightstep. Lightstep supports both OpenTelemetry and OpenTracing. Both 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.

There are two basic types of instrumentation: using an auto-installer to instrument your framework and using the APIs to instrument operations inside your services. Instrumenting your framework generally means that an agent or wrapper instruments RPC frameworks, clients and other common libraries, either by modifying code at runtime or by integrating like a plug-in as a dependency to your existing frameworks and libraries. This type of instrumentation basically provides observability into a request as it travels from service to service. Instrumenting your inside your services provides observability into the operations within the service. You’ll likely need to do both to get the granular observability needed to take full advantage of the root cause analysis and performance monitoring in Lightstep.

Best Practice: Start with instrumenting at the framework level. This often requires no code changes at the service level (depending on the language) and is a quick way to start. Once that’s in place, you’ll be able to see where the blind spots are in your system and you can start adding service-level instrumentation as needed.

Get Started with OpenTelemetry

OpenTelemetry is currently in Beta and 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.

Here are some resources to get you started:

Get Started with OpenTracing

The OpenTracing API provides a standard, vendor-neutral framework for instrumentation of your code. It consists of an API specification, frameworks, and libraries that have implemented the specification.

Consider using OpenTelemetry if you’re just starting your instrumentation.

Here are some resources to get you started:

See Your Data in Lightstep

Now that you have data reporting to Lightstep, it’s time to see how to you can use Lightstep for root cause analysis, deployment monitoring, and monitoring.