Quickstart: Tracing instrumentation

Cloud Observability supports OpenTelemetry as the way to get telemetry data (traces, logs, and metrics) from your app as requests travel through its many services and other infrastructure.

Auto-Instrumentation & Manual Instrumentation

There are two ways to instrument your code:

  • Auto-instrumentation
  • Manual instrumentation

Auto-instrumentation uses shims or bytecode instrumentation agents to intercept your code at runtime or at compile-time to add tracing and metrics instrumentation to the libraries and frameworks you depend on.

Manual instrumentation uses an SDK and APIs you call from your services to provide observability into the operations within a service. It requires you to manually add spans, context propagation, attributes, etc. to your application code. It is akin to commenting code or writing tests.

As a general rule of thumb, it is best to start with auto-instrumentation if it’s available. Once that’s in place, you’ll be able to see where the blind spots are in your system and you can start adding manual instrumentation as needed.

Sending Traces to Cloud Observability Quickly Using Auto-Instrumentation

Don’t see your language listed below? No problem! As long as you use a language supported by OpenTelemetry, you can send Traces to Cloud Observability, either directly to Cloud Observability, or through a Collector.

  • Use the Java auto-instrumentation agent to configure OpenTelemetry, auto-instrument your code, and send data to Cloud Observability. The agent dynamically injects bytecode to capture telemetry from many libraries and frameworks.

    Step 1: Download the Java agent

    The Java agent JAR file includes the agent and instrumentation libraries.

    To download the JAR file, go to OpenTelemetry’s Java instrumentation releases, click Assets, and click opentelemetry-javaagent.jar. Add the JAR file to your preferred directory.

    Step 2: Add the Java agent to your JVM startup arguments

    Add the downloaded JAR file path and your service name to your JVM startup arguments. Do this on the command line, replacing <service_name> with your own value:

    1

    java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=<service_name> -jar path/to/myapp.jar

    Step 3: Run the Java agent

    To run the Java agent, enter the following in your terminal, replacing <LS_ACCESS_TOKEN> and <service_name> with your own values.

    1
2
3
4
5
6
7
8
9
10

    export OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN>"

java -javaagent:opentelemetry-javaagent.jar \
           -Dotel.service.name=<service_name> \
           -Dotel.traces.exporter=logging,otlp \
           -Dotel.metrics.exporter=logging,otlp \
           -Dotel.exporter.otlp.protocol=grpc \
           -Dotel.exporter.otlp.endpoint="https://ingest.lightstep.com:443" \ #US data center
           #-Dotel.exporter.otlp.endpoint="https://ingest.eu.lightstep.com:443" \ #EU data center
           -jar path/to/your/app.jar

    This approach sends data to Cloud Observability directly and doesn’t use the Collector.

    Step 4: Call your Java application

    Generate traffic in your application to create telemetry data.

    Sending OpenTelemetry data directly to Cloud Observability without a Collector for most developer setups suffices. For non-development setups, however, it is highly recommended that you send OpenTelemetry data to Cloud Observability Observability using the OpenTelemetry Collector.

  • Use the Node.js auto-instrumentation package to configure OpenTelemetry, auto-instrument your code, and send data to Cloud Observability. The module dynamically instruments many libraries and frameworks to capture telemetry.

    Step 1: Install the auto-instrumentation package

    Run the following commands to install the appropriate packages:

    1
2

    npm install @opentelemetry/api
npm install @opentelemetry/auto-instrumentations-node

    Step 2: Start your application

    Configure the OpenTelemetry SDK using environment variables to send your data to Cloud Observability.

    Enter the commands below, replacing <LS_ACCESS_TOKEN> and <SERVICE_NAME> with your own values:

    1
2
3
4
5

    export OTEL_SERVICE_NAME="<SERVICE_NAME>"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.lightstep.com" #US data center
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.eu.lightstep.com" #EU data center
export OTEL_EXPORTER_OTLP_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN>"
node --require @opentelemetry/auto-instrumentations-node/register app.js

    Step 3: Call your Node.js application

    Generate traffic in your application to create telemetry data.

    Sending OpenTelemetry data directly to Cloud Observability without a Collector for most developer setups will suffice. For non-development setups, however, it is highly recommended that you send OpenTelemetry data to Cloud Observability by way of the OpenTelemetry Collector.

  • Use the Python auto-instrumentation agent to configure OpenTelemetry, auto-instrument your code, and send data to Cloud Observability. The agent dynamically injects bytecode to capture telemetry from many libraries and frameworks.

    Step 1: Download and install the Python agent

    Run the following commands to install the appropriate packages:

    1
2
3
4

    pip install opentelemetry-distro \ 
  opentelemetry-exporter-otlp

opentelemetry-bootstrap -a install

    Step 2: Run the Python agent

    Configure your agent using environment variables to send your data to Cloud Observability. Enter the commands below, replacing <LS_ACCESS_TOKEN> and <service_name> with your own values:

    1
2
3
4
5
6
7
8

    export OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN>"
export OTEL_TRACES_EXPORTER="console,otlp_proto_grpc"
export OTEL_METRICS_EXPORTER="console,otlp_proto_grpc"
export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_ENDPOINT="ingest.lightstep.com:443" #US data center
#export OTEL_EXPORTER_OTLP_ENDPOINT="ingest.eu.lightstep.com:443" #EU data center

opentelemetry-instrument python app.py

    Step 3: Call your Python application

    Generate traffic in your application to create telemetry data.

    Sending OpenTelemetry data directly to Cloud Observability without a Collector for most developer setups will suffice. For non-development setups, however, it is highly recommended that you send OpenTelemetry data to Cloud Observability Observability by way of the OpenTelemetry Collector.

  • Go instruments application by using instrumentation libraries to wrap key infrastructure components. These libraries can be found in the Contrib repository or the OpenTelemetry Registry.

    Step 1: Install dependencies and set up the Tracer Provider

    Run the following command to get the needed dependencies.

    1
2
3
4

    go get go.opentelemetry.io/otel \
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc \
    go.opentelemetry.io/otel/sdk/trace \
    go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

    Import the following package for configuring OTEL and the net/http instrumentation.

    1
2
3
4
5
6

    import (
	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

    Configure the OTEL Tracer Provider and the OTLP Exporter.

    1
2
3
4
5
6
7
8
9

    exp, err := otlptracegrpc.New(context.Background())
if err != nil {
    panic(err)
}
otel.SetTracerProvider(
    sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
    ),
)

    Step 2: Wrap HTTP routes with an OTEL Handler

    Add otelhttp as a wrapper around your http handlers.

    1
2
3
4
5

    mux := http.NewServeMux()
// The Root Route is not instrumented
mux.Handle("/", echo("Hello World"))
// The /foo route is instrumented
mux.Handle("/foo", otelhttp.NewHandler(echo("foo"), "foo"))

    Step 3: Run the application

    Configure your SDK using environment variables to send your data to Cloud Observability.

    Enter the commands below, replacing <LS_ACCESS_TOKEN> and <SERVICE_NAME> with your own values:

    1
2
3
4
5
6
7

    #NOTE if your access token has a "+" it must be URL Encoded to "%2B"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN>"
export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.lightstep.com:443" #US data center
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.eu.lightstep.com:443" #EU data center

go run .

    Step 4: Call your Go application

    Generate traffic in your application to create telemetry data.

    Sending OpenTelemetry data directly to Cloud Observability without a Collector for most developer setups suffices. For non-development setups, however, it is highly recommended that you send OpenTelemetry data to Cloud Observability Observability using the OpenTelemetry Collector.

  • Use the .NET auto-instrumentation agent to configure OpenTelemetry, auto-instrument your code, and send data to Cloud Observability. The agent dynamically injects bytecode to capture telemetry from many libraries and frameworks.

    Step 1: Download and install the .NET agent

    The .NET agent includes the agent and instrumentation libraries.

    To download and install the agent, go to OpenTelemetry’s .NET instrumentation releases, check the latest released version, and run the following in your server:

    1
2
3

    # Download and install the latest version, e.g. 0.7.0
curl -sSfL https://raw.githubusercontent.com/open-telemetry/opentelemetry-.NET-instrumentation/0.7.0/otel-.NET-auto-install.sh -O
sh ./otel-.NET-auto-install.sh

    This will install it to $HOME/.otel-dotnet-auto by default.

    Step 2: Set up instrumentation for the current shell session

    The installed agent must be explicitly enabled in the .NET runtime. Run the script included in the installation in order to set the respective options:

    1
2

    chmod +x $HOME/.otel-dotnet-auto/instrument.sh
. $HOME/.otel-dotnet-auto/instrument.sh

    Step 3: Run the .NET agent

    To run the .NET agent, enter the following in your terminal, replacing <LS_ACCESS_TOKEN> and <service_name> with your own values.

    1
2
3
4
5
6
7

    export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.lightstep.com:443" #US data center
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.eu.lightstep.com:443" #EU data center
export OTEL_EXPORTER_OTLP_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN>"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"
.NET run --project MyApplication

    This approach sends data to Cloud Observability directly and doesn’t use the Collector.

    Step 4: Call your .NET application

    Generate traffic in your application to create telemetry data.

    Sending OpenTelemetry data directly to Cloud Observability without a Collector for most developer setups suffices. For non-development setups, however, it is highly recommended that you send OpenTelemetry data to Cloud Observability Observability using the OpenTelemetry Collector.

Remember, Cloud Observability can only display what your system sends it, so instrumentation is key!

Updated Jun 13, 2022