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.

If you’re using the Hipster Shop, the adservice is already instrumented using OpenTelemetry.

Using a different language? You can still get started quickly.

Configure

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.

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 Instrumentation

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.

Then begin collecting traces! In Java, Javascript, and Python, OpenTelemetry has built-in instrumentation for popular libraries, so that you can get tracing data without needing to add any tracing code.

For Java, you need to know the latest version of the lightstep-opentelemetry-javaagent.jar.

Start tabs

Java

1
2
3
4
5

# Install the OpenTelemetry Java Agent
# You'll need to know the version number of the latest release: https://github.com/lightstep/otel-launcher-java/releases/latest/
curl -L "https://github.com/lightstep/otel-launcher-java/releases/download/<VERSION>/lightstep-opentelemetry-javaagent-<VERSION>.jar" > lightstep-opentelemetry-javaagent-<VERSION>.jar
# Run your application with the agent
java -javaagent:path/to/lightstep-opentelemetry-javaagent-<VERSION>.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

How the adservice Implemented OpenTelemetry

The adservice in the Hipster Shop is already implemented to use OpenTelemetry. Here’s how.

  • The Lightstep access token and the service name are set as environment variables in the service’s Kubernetes manifest (\kubernetes-manifests\adservice.yml).

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

      spec:
    terminationGracePeriodSeconds: 5
    containers:
      - name: server
        image: adservice
        ports:
          - containerPort: 9555
        env:
          - name: PORT
            value: "9555"
          # Lightstep config
          - name: LS_SERVICE_NAME
            value: "adservice"
          - name: LS_ACCESS_TOKEN
            valueFrom:
              secretKeyRef:
                name: lightstep-credentials
                key: accessToken
  • The lightstep-opentelemetry-javaagent-0.08.1.jar is downloaded to the \src\adservice directory.
  • The build.gradle file runs the service using the Java Agent. 
    1
2
3
4
5
6
7
8
9
10
11
12

      task adServiceClient(type: CreateStartScripts) {
  mainClassName = 'hipstershop.AdServiceClient'
  applicationName = 'AdServiceClient'
  outputDir = new File(project.buildDir, 'tmp')
  classpath = jar.outputs.files + project.configurations.runtime
  defaultJvmOpts =
      [
       "-Dlog4j2.contextDataInjector=io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector",
      //"-agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=adserviceclient,-cprof_service_version=1.0.0",
      "-javaagent:/app/lightstep-opentelemetry-javaagent-0.08.1.jar"
      ]
  }

Run Your Service or App

Now that you’ve instrumented a service (or if using the Hipster Shop, seen how services can be instrumented), it’s time to run your app so you can view the telemetry data in Lightstep.

If you’re using the Hipster shop, follow these instructions to run it locally. Visit the Donut shop and order a few things to generate some data.

Otherwise, simply run your app to generate some data.

What Did We Learn?

  • Lightstep has Launchers for OpenTelemetry that let you instrument your service with a single line of code.
  • The adservice in the Hipster shop is already configured to use OpenTelemetry by adding 2 environment variables and running it with the downloaded Java agent.