Node.js App Instrumentation

Follow the steps below to auto-instrument your Node.js service. When complete, your service will start emitting logs, metrics, and traces to Lakerunner.

Local Testing

1. Get a Cardinal API key.

   Follow the steps in the Overview to mint an ingest API key.

2. Install the OpenTelemetry auto-instrumentation dependencies:

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

3. Enable log forwarding.

   See the Pino Logger section below.

4. Export the following environment variables:

   export OTEL_SERVICE_NAME="your-service-name" # Set your service name
   export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=local" # local/dev/staging/prod
   export OTEL_METRICS_EXPORTER="otlp"
   export OTEL_LOGS_EXPORTER="otlp"
   export OTEL_TRACES_EXPORTER="otlp"
   export OTEL_EXPORTER_OTLP_ENDPOINT="https://otelhttp.intake.<your-region>.aws.cardinalhq.io"
   export OTEL_EXPORTER_OTLP_HEADERS="x-cardinalhq-api-key=<your-api-key>" # Set your API key
   export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

5. Run your application:

   npm run start # Or your application's start script

6. Validate that Lakerunner is receiving data.

   Exercise the service by calling some API endpoints or causing some logs and metrics to be emitted. Wait a few minutes, then query for your service in the Cardinal dashboard.

Docker

Set the environment variables outlined above in your Docker container runtime configuration.

• Update OTEL_RESOURCE_ATTRIBUTES to set deployment.environment.name for your environment.
• If you run an OpenTelemetry Collector, set OTEL_EXPORTER_OTLP_ENDPOINT to your Collector’s OTLP receiver endpoint, and forward to Lakerunner from the Collector. See Already running an OpenTelemetry Collector?.

Kubernetes

Set the environment variables outlined above in your Deployment or StatefulSet manifest.

• Update OTEL_RESOURCE_ATTRIBUTES to set deployment.environment.name for your environment.
• If you run an OpenTelemetry Collector, set OTEL_EXPORTER_OTLP_ENDPOINT to your Collector’s OTLP receiver endpoint, and forward to Lakerunner from the Collector. See Already running an OpenTelemetry Collector?.

Additional Integrations

Pino Logger

Configure Pino  to forward logs to Lakerunner.

1. Install the pino-opentelemetry-transport package:

   npm install --save pino-opentelemetry-transport

2. Configure Pino to use the pino-opentelemetry-transport when you initialize the logger:

   const logger = pino({
     transport: {
       targets: [
         {
           target: "pino/file",
           options: { destination: 1 }, // continues to write to stdout
         },
         {
           target: "pino-opentelemetry-transport",
           options: {},
         },
       ],
     },
   });