Telemetry

Quick and easy telemetry setup

AXAR comes with built-in support for OpenTelemetry to collect telemetry data. OpenTelemetry is an open-source framework that helps you capture and analyze what's happening in your app.

Getting started

Good news - there's nothing extra you need to do to enable telemetry! If you've already set up OpenTelemetry in your project, AXAR will automatically hook into it. Here's how you can get started with NodeSDK.

Step 1: Install dependencies

First, install the required OpenTelemetry packages:

npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

Step 2: Set up NodeSDK

Now, add the following setup in your code:

// Other imports...

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'TelemetryExample',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
});

// Your agent code goes here...

async function main() {
  // Start the sdk
  sdk.start();
  try {
    const response = await new GreetingAgent().run({
      userName: 'Alice',
      userMood: 'happy',
      language: 'English',
    });
    console.log(response);
  } finally {
    // Don't forget to shutdown
    await sdk.shutdown();
  }
}

main().catch(console.error);

✔ Full code example can be found here: https://github.com/axar-ai/axar/blob/main/examples/telemetry/greeting-agent-with-telemetry.ts

For cleaner code, consider moving the telemetry setup into its own config file or following best practices for your framework/platform.

Testing your setup

To test telemetry locally, you'll need an OpenTelemetry collector and a compatible backend. We recommend using the OpenTelemetry dev environment.

Once everything is running, you can visualize traces using Jaeger or Zipkin.

Deployment

To deploy OpenTelemetry in production, check out the OpenTelemetry Collector Getting Started guide. It walks you through setting up the collector and configuring it to receive data from your app.