OpenTelemetry Instrumentation for Dust

[!NOTE] What is this? Dust is an AI agent platform for building custom assistants. OpenTelemetry is an observability framework for collecting traces, metrics, and logs from applications.

This instrumentation package provides automatic observability using OpenTelemetry for Dust agent interactions, enabling you to monitor agent performance, track tool executions, debug failures, and analyze conversation patterns. Read more about AI agent observability.

[!IMPORTANT] This is an unofficial and experimental package. It is not affiliated with or endorsed by Dust or OpenTelemetry. Breaking changes may occur between versions.

Open source OpenTelemetry instrumentation package for the Dust SDK that automatically captures agent interactions as distributed traces following the GenAI Semantic Conventions.

Installation

npm install @stefano.amorelli/opentelemetry-instrumentation-dust
# or
yarn add @stefano.amorelli/opentelemetry-instrumentation-dust
# or
pnpm add @stefano.amorelli/opentelemetry-instrumentation-dust
# or
bun add @stefano.amorelli/opentelemetry-instrumentation-dust

Usage

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { DustInstrumentation } from '@stefano.amorelli/opentelemetry-instrumentation-dust';

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new DustInstrumentation({
      captureMessageContent: true,  // Capture message content (default: false)
    }),
  ],
});

// IMPORTANT: Import Dust SDK AFTER instrumentation registration
const { DustAPI } = require('@dust-tt/client');

// All Dust API calls are now automatically traced
const dustAPI = new DustAPI(
  { url: 'https://dust.tt' },
  { workspaceId: 'your-workspace-id', apiKey: 'your-api-key' }
);

Span Mapping

This instrumentation maps Dust SDK operations to OpenTelemetry spans following the GenAI semantic conventions:

| Dust SDK Method | OpenTelemetry Span | Operation Name | Key Attributes | |-----------------|-------------------|----------------|----------------| | createConversation() | invoke_agent {agent_id} | invoke_agent | gen_ai.conversation.idgen_ai.agent.idgen_ai.response.idenduser.idgen_ai.input.messages (opt-in) | | streamAgentAnswerEvents() | invoke_agent | invoke_agent | gen_ai.conversation.idgen_ai.agent.namegen_ai.agent.descriptiondust.agent.versiondust.agent.version_created_atgen_ai.usage.output_tokensgen_ai.response.finish_reasonsgen_ai.output.messages (opt-in) | | Event: agent_action_success | execute_tool (child span) | execute_tool | gen_ai.tool.namegen_ai.tool.call.idgen_ai.tool.call.arguments (opt-in)gen_ai.tool.call.result (opt-in) |

All spans include:

• gen_ai.provider.name = "dust"
• gen_ai.operation.name = operation type
• Error tracking via error.type and span status

[!NOTE] The enduser.id attribute is automatically populated from the email field in the conversation context (args.message.context.email), if available. This allows you to track usage and issues per user.

Custom Dust Attributes

This instrumentation uses custom dust.* attributes for Dust-specific features not yet covered by OpenTelemetry semantic conventions:

| Attribute | Type | Description | |-----------|------|-------------| | dust.agent.version | number | Agent configuration version number | | dust.agent.version_created_at | string | Timestamp when this agent version was created | | dust.retrieval.documents | string (JSON) | Retrieved documents from RAG operations |

These custom attributes follow the same namespacing pattern used by other OpenTelemetry instrumentations for vendor-specific features.

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable instrumentation | | captureMessageContent | boolean | false | Capture message content, tool arguments, and results | | captureSystemInstructions | boolean | false | Capture system instructions |

[!NOTE] captureMessageContent and captureSystemInstructions are opt-in (default: false) to avoid capturing sensitive data such as PII, credentials, or proprietary information. See OpenTelemetry GenAI semantic conventions on sensitive information for details.

new DustInstrumentation({
  enabled: true,
  captureMessageContent: true,
  captureSystemInstructions: false,
})

Testing

# Run automated tests
npm test

# Run manual test with real Dust API
cp .env.example .env
# Edit .env with your DUST_WORKSPACE_ID, DUST_API_KEY, and DUST_URL
npm run manual-test

Visualizing Traces

For quick testing and debugging, you can visualize traces in a waterfall view using Jaeger, an open-source distributed tracing platform. This shows the complete agent invocation hierarchy including tool executions and timing information.

# Start Jaeger (all-in-one Docker image for local testing)
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

# Run manual test with OTLP export enabled
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 npm run manual-test

# Open Jaeger UI in your browser
# Visit http://localhost:16686 and select service "dust-manual-test"

License

GPL-3.0

Copyright © 2025 Stefano Amorelli · [email protected]