Tracing Enablement

  • 5 minute(s) read
Prev Next

Catchpoint Tracing relies on instrumentation added to your applications to capture telemetry data and send it to Catchpoint’s' tracing collector. To integrate data from your applications with Catchpoint, select your application runtime environment below and follow the instructions.

Catchpoint Tracing follows the OpenTelemetry (OTEL) standard, making it easy to integrate tracing data into various applications. For general information on integrating with OTEL SDKs, check the OTEL SDK instrumentation doc here: https://opentelemetry.io/docs/concepts/instrumentation

Use the script below to set up the instrumentation and run your application. You will need to replace some variables in the script with your specific values. Read the instructions following the script for more details.

export OTEL_SERVICE_NAME=APPLICATION_NAME
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.tracing.catchpoint.com
export OTEL_EXPORTER_OTLP_HEADERS=x-catchpoint-api-key=REPLACE_WITH_YOUR_API_KEY
# Uncomment the following line if you want to specify your service/application's type.
# export OTEL_RESOURCE_ATTRIBUTES=service.type=APPLICATION_TYPE 
export JAVA_TOOL_OPTIONS="-javaagent:./otel-trace/otel-agent.jar"

# RUNNING YOUR APPLICATION
# Run your JAVA application as normal, and the OTEL instrumentation should function
# Example:
# java -Xms512m -Xmx512m \
#    -Dspring.profiles.active=todo-service \
#    -Dgrpc.user.enabled=true -Dotel.instrumentation.aws-sdk.experimental-use-propagator-for-# messaging=true \
#    -jas ./target/todo-app.jar

  1. Download the OpenTelemetry Java instrumentation from here:
    https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

  2. Insert your Catchpoint API Key in the fourth line of the script.

  3. Under the "RUNNING YOUR APPLICATION" section in the script, add the command to run your java application as normal. An example command is provided in the script for reference.

Use the script below to set up the instrumentation and run your application. You will need to replace some variables in the script with your specific values. Read the instructions following the script for more details.

export OTEL_SERVICE_NAME=APPLICATION_NAME
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.tracing.catchpoint.com
export OTEL_EXPORTER_OTLP_HEADERS=x-catchpoint-api-key=REPLACE_WITH_YOUR_API_KEY
# Uncomment the following line if you want to specify your service/application's type.
# export OTEL_RESOURCE_ATTRIBUTES=service.type=APPLICATION_TYPE 
export OTEL_TRACES_EXPORTER=otlp
export OTEL_NODE_RESOURCE_DETECTORS=env,host

npm install -save @opentelelmetry/api
npm install -save @opentelelmetry/auto-instrumentations-node
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node ./REPLACE_WITH_PATH_TO_YOUR_APPLICATION/bin/www

  1. Insert your Catchpoint API Key in the fourth line of the script.

  2. Insert the correct path to your application in the last line of the script.

Use the script below to set up the instrumentation and run your application. You will need to replace some variables in the script with your specific values. Read the instructions following the script for more details.

export OTEL_SERVICE_NAME=APPLICATION_NAME
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.tracing.catchpoint.com
export OTEL_EXPORTER_OTLP_HEADERS=x-catchpoint-api-key=REPLACE_WITH_YOUR_API_KEY
# Uncomment the following line if you want to specify your service/application's type. (Catchpoint Tracing displays different icons for different application types.)
# export OTEL_RESOURCE_ATTRIBUTES=service.type=APPLICATION_TYPE 
export GRPC_DNS_RESOLVER=DNS_RESOLVER_NAME

pip install opentelemetry-distro \
opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
PORT=8000 opentelemetry-instrument python3 ./APPLICATION_PATH/APPLICATION_NAME.py

  1. Insert your Catchpoint API Key in the fourth line of the script.

  2. Replace "DNS_RESOLVER_NAME" with your desired DNS resolver name or IP.

  3. In the last line of the script, insert your application’s path and name.

Use the script below to set up the instrumentation and run your application. You will need to replace some variables in the script with your specific values. Read the instructions following the script for more details.

export OTEL_SERVICE_NAME=APPLICATION_NAME
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.tracing.catchpoint.com
export OTEL_EXPORTER_OTLP_HEADERS=x-catchpoint-api-key=REPLACE_WITH_YOUR_API_KEY
# Uncomment the following line if you want to specify your service/application's type.
# export OTEL_RESOURCE_ATTRIBUTES=service.type=APPLICATION_TYPE 

curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
chmod +x otel-dotnet-auto-install.sh
sh ./otel-dotnet-auto-install.sh
chmod +x $HOME/.otel-dotnet-auto/instrument.sh
$HOME./otel-dotnet-auto/instrument.sh
dotnet build ./APPLICATION_PATH/APPLICATION_NAME.csproj 
dotnet run --project ./APPLICATION_PATH/APPLICATION_NAME.csproj

  1. Insert your Catchpoint API Key in the fourth line of the script.

  2. In the last two lines of the script, insert your application’s path and name.

  1. Make sure you have cert-manager installed:

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml

  2. Install OpenTelemetry Kubernetes Operator:

    kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

    Check “OpenTelemetry Operator for Kubernetes” document for more details: https://opentelemetry.io/docs/kubernetes/operator

  3. Create OpenTelemetry Collector by replacing <CP-TRACING-API-KEY> with your actual Catchpoint Tracing API key (or you may use Kubernetes Secrets):

    kubectl apply -f - <<EOF

    apiVersion: opentelemetry.io/v1alpha1

    kind: OpenTelemetryCollector

    metadata:

     name: otel

    spec:

     config:|

       receivers:

         otlp:

           protocols:

             grpc:

               endpoint: 0.0.0.0:4317

             http:

               endpoint: 0.0.0.0:4318

       processors:

         batch:

       exporters:

         otlp:

           endpoint: otel-collector.tracing.catchpoint.com:443

           headers:

             x-catchpoint-api-key: "<CP-TRACING-API-KEY>"

       service:

         pipelines:

           traces:

             receivers: [otlp]

             processors: [batch]

             exporters: [otlp]

    EOF

  4. Check “Create an OpenTelemetry Collector” section here for more details: https://opentelemetry.io/docs/kubernetes/operator/automatic/#create-an-opentelemetry-collector-optional

    kubectl apply -f - <<EOF

    apiVersion: opentelemetry.io/v1alpha1

    kind: Instrumentation

    metadata:

     name: otel-instrumentation

    spec:

     exporter:

       endpoint: http://otel-collector.opentelemetry-operator-system:4317

     propagators:

       - tracecontext

       - baggage

     sampler:

       type: always_on

     env:

       - name: OTEL_TRACES_EXPORTER

         value: otlp

       - name: OTEL_EXPORTER_OTLP_PROTOCOL

         value: grpc

    EOF

If you need runtime-specific customization of instrumentation, check the “Configure Auto Instrumentation” section here for more details: https://opentelemetry.io/docs/kubernetes/operator/automatic/#configure-automatic-instrumentation

  1. Next, mark your services to be traced with OpenTelemetry auto instrumentation annotation. The annotation is added into your service’s spec.template.metadata.annotations to include a language-specific annotation:

    - Java: instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/otel-instrumentation"

    - Node.js: instrumentation.opentelemetry.io/inject-nodejs: "opentelemetry-operator-system/otel-instrumentation"

    - Python: instrumentation.opentelemetry.io/inject-python: "opentelemetry-operator-system/otel-instrumentation"

    - .NET: instrumentation.opentelemetry.io/inject-dotnet: "opentelemetry-operator-system/otel-instrumentation"

    - Go: instrumentation.opentelemetry.io/inject-go: "opentelemetry-operator-system/otel-instrumentation"


    For example, you can annotate a service named “my-service” (Java):

    apiVersion: apps/v1

    kind: Deployment

    metadata:

     name: my-service

     labels:

       app: my-service

    spec:

     replicas: 1

     selector:

       matchLabels:

         app: my-service

     template:

       metadata:

         annotations:

           instrumentation.opentelemetry.io/inject-java: 'opentelemetry-operator-system/otel-instrumentation'

         labels:

           app: todo-service

     ...

     ...

     ...

    apiVersion: apps/v1

    kind: Deployment

    metadata:

     name: my-service

     labels:

       app: my-service

    spec:

     replicas: 1

     selector:

       matchLabels:

         app: my-service

     template:

       metadata:

         annotations:

           instrumentation.opentelemetry.io/inject-java: 'opentelemetry-operator-system/otel-instrumentation'

         labels:

           app: todo-service

     ...

     ...

     ...

  • If the services are already deployed before OpenTelemetry Kubernetes Operator, OpenTelemetry Collector and OpenTelemetry Instrumentation Resource setup (as described above):

    • EITHER:

      You can rollout services, so new started services will be auto instrumented. For example, you can use the following command to rollout the services named “my-service”

      kubectl rollout restart deployment my-service

    • OR

      You can patch the existing services by marking them to be auto instrumented. For example, you can use the following command to patch the services named “my-service” (Java)

      kubectl patch deployment.apps/my-service -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-java": "opentelemetry-operator-system/otel-instrumentation"}}}}}'

https://opentelemetry.io/docs/kubernetes/operator/automatic/#add-annotations-to-existing-deployments

Supported Service/Application Types

Optionally, you can specify the type of your application/service. Applications/services whose types are known are shown with their type-specific icons in the Catchpoint Tracing portal. By default, Catchpoint Tracing will try to resolve application type through resource attributes of your spans, but it may not always be resolved this way. If the application/service type cannot be resolved, the runtime-specific (java, nodejs, python, go, dotnet, php, ruby, etc...) icon is shown. Follow these steps to specify application type:

  1. Locate this line in the script and uncomment it (remove the # symbol):
    # export OTEL_RESOURCE_ATTRIBUTES=service.type=APPLICATION_TYPE

  2. Replace "APPLICATION_TYPE" in the previous line with a supported application type value.

Below is the list of supported application/service types (please let us know if there are additional application/service types you want to show with their own icons in the portal):

  • aspcore

  • aws-lambda

  • cpp

  • django

  • dotnet

  • entityframework

  • erlang

  • express

  • fastapi

  • flask

  • go

  • hapi

  • java

  • koa

  • nodejs

  • php

  • python

  • ruby

  • rust

  • spring

  • swift

  • tornado