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.id gen_ai.agent.id gen_ai.response.id enduser.id gen_ai.input.messages (opt-in)
streamAgentAnswerEvents()	invoke_agent	invoke_agent	gen_ai.conversation.id gen_ai.agent.name gen_ai.agent.description dust.agent.version dust.agent.version_created_at gen_ai.usage.output_tokens gen_ai.response.finish_reasons gen_ai.output.messages (opt-in)
Event: agent_action_success	execute_tool (child span)	execute_tool	gen_ai.tool.name gen_ai.tool.call.id gen_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 · stefano@amorelli.tech