Add DBNL Telemetry Exporter (#1111)

Add support for exporting telemetry to DBNL.

Closes #1107

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.



## Summary by CodeRabbit

* **New Features**
  * Added DBNL telemetry exporter to enable tracing and observability integration.

* **Documentation**
  * Added a DBNL integration guide, new observability workflow page, and updated provider/integrations lists and table of contents to include DBNL.

* **Examples**
  * Added DBNL configuration and a sample observability tutorial showing installation, credential setup, and how to analyze traces.

Authors:
  - Renaud Bourassa (https://github.com/dbnl-renaud)

Approvers:
  - Will Killian (https://github.com/willkill07)

URL: #1111

Author: dbnl-renaud

docs/source/extend/telemetry-exporters.md

@@ -78,6 +78,7 @@ Examples of existing telemetry exporters include:
 - **Patronus**: Exports traces to Patronus via OTLP
 - **Galileo**: Exports traces to Galileo via OTLP
 - **RagaAI Catalyst**: Exports traces to RagaAI Catalyst
+- **DBNL**: Exports traces to DBNL via OTLP
 
 ## Quick Start: Your First Telemetry Exporter
 
@@ -244,7 +245,7 @@ Specialized for OpenTelemetry-compatible services with many pre-built options:
 - **Use case**: OTLP-compatible backends, standard observability tools
 - **Base class**: `OtelSpanExporter`
 - **Data flow**: `IntermediateStep` → `Span` → [Processing Pipeline] → `OtelSpan` → Export
-- **Pre-built integrations**: Langfuse, LangSmith, OpenTelemetry Collector, Patronus, Galileo, Phoenix, RagaAI, Weave
+- **Pre-built integrations**: Langfuse, LangSmith, OpenTelemetry Collector, Patronus, Galileo, Phoenix, RagaAI, Weave, DBNL
 
 #### Advanced Custom Exporters
 
@@ -269,6 +270,7 @@ Before creating a custom exporter, check if your observability service is alread
 
 | Service | Type | Installation | Configuration |
 |---------|------|-------------|---------------|
+| **DBNL** | `dbnl` | `pip install "nvidia-nat[opentelemetry]"` | API URL + API token + project id |
 | **File** | `file` | `pip install nvidia-nat` | local file or directory |
 | **Langfuse** | `langfuse` | `pip install "nvidia-nat[opentelemetry]"` | endpoint + API keys |
 | **LangSmith** | `langsmith` | `pip install "nvidia-nat[opentelemetry]"` | endpoint + API key |

docs/source/workflows/observe/index.md

@@ -133,6 +133,7 @@ Each exporter has its own detailed configuration guide with complete setup instr
 - **[Catalyst](https://catalyst.raga.ai/)** - See [Observing with Catalyst](./observe-workflow-with-catalyst.md)
 - **Custom Exporters** - See [Adding Telemetry Exporters](../../extend/telemetry-exporters.md) for creating custom integrations
 - **[NVIDIA Data Flywheel Blueprint](https://build.nvidia.com/nvidia/build-an-enterprise-data-flywheel)** - See [Observing with Data Flywheel](./observe-workflow-with-data-flywheel.md)
+- **[DBNL](https://distributional.com/)** - See [Observing with DBNL](./observe-workflow-with-dbnl.md)
 - **[Dynatrace](https://dynatrace.com/)** - See [Observing with Dynatrace](./observe-workflow-with-dynatrace.md)
 - **File Export** - Built-in file-based tracing for local development and debugging
 - **[Galileo](https://galileo.ai/)** - See [Observing with Galileo](./observe-workflow-with-galileo.md)
@@ -151,6 +152,7 @@ For complete configuration examples and setup instructions, refer to the individ
 |----------|-----------|
 | Catalyst | Logging, Tracing |
 | Data Flywheel | Logging, Tracing |
+| DBNL | Logging, Tracing |
 | Dynatrace | Logging, Tracing |
 | Galileo | Logging, Tracing |
 | Langfuse | Logging, Tracing |
@@ -202,6 +204,7 @@ For complete information about developing and integrating custom telemetry expor
 
 Observing with Catalyst <./observe-workflow-with-catalyst.md>
 Observing with Data Flywheel <./observe-workflow-with-data-flywheel.md>
+Observing with DBNL <./observe-workflow-with-dbnl.md>
 Observing with Dynatrace <./observe-workflow-with-dynatrace.md>
 Observing with Galileo <./observe-workflow-with-galileo.md>
 Observing with OTEL Collector <./observe-workflow-with-otel-collector.md>

docs/source/workflows/observe/observe-workflow-with-dbnl.md

@@ -0,0 +1,96 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Observing a Workflow with DBNL
+
+This guide provides a step-by-step process to enable observability in a NeMo Agent toolkit workflow using DBNL for tracing. By the end of this guide, you will have:
+
+- Configured telemetry in your workflow.
+- Ability to view traces in the DBNL platform.
+
+## Step 1: Install DBNL
+
+Visit [https://docs.dbnl.com/get-started/quickstart](https://docs.dbnl.com/get-started/quickstart) to install DBNL.
+
+## Step 2: Create a Project
+
+Create a new Trace Ingestion project in DBNL. To create a new project in DBNL:
+
+1. Navigate to your DBNL deployment (e.g. <http://localhost:8080/>)
+2. Go to Projects > + New Project
+3. Name your project `nat-calculator`
+4. Add a LLM connection to your project
+5. Select Trace Ingestion as the project Data Source
+6. Click on Generate API Token and note down the generated **API Token**
+7. Note down the **Project Id** for the project
+
+## Step 3: Configure Your Environment
+
+Set the following environment variables in your terminal:
+
+```bash
+# DBNL_API_URL should point to your deployment API URL (e.g. http://localhost:8080/api)
+export DBNL_API_URL=<your_api_url>
+export DBNL_API_TOKEN=<your_api_token>
+export DBNL_PROJECT_ID=<your_project_id>
+```
+
+## Step 4: Install the NeMo Agent toolkit OpenTelemetry Subpackages
+
+```bash
+# Install specific telemetry extras required for DBNL
+uv pip install -e '.[opentelemetry]'
+```
+
+## Step 5: Modify NeMo Agent toolkit Workflow Configuration
+
+Update your workflow configuration file to include the telemetry settings.
+
+Example configuration:
+```yaml
+general:
+  telemetry:
+    tracing:
+      dbnl:
+        _type: dbnl
+```
+
+## Step 6: Run the workflow
+
+From the root directory of the NeMo Agent toolkit library, install dependencies and run the pre-configured `simple_calculator_observability` example.
+
+**Example:**
+
+```bash
+# Install the workflow and plugins
+uv pip install -e examples/observability/simple_calculator_observability/
+
+# Run the workflow with DBNL telemetry settings
+# Note: you may have to update configuration settings based on your DBNL deployment
+nat run --config_file examples/observability/simple_calculator_observability/configs/config-dbnl.yml --input "What is 1*2?"
+```
+
+As the workflow runs, telemetry data will start showing up in DBNL.
+
+## Step 7: Analyze Traces Data in DBNL
+
+Analyze the traces in DBNL. To analyze traces in DBNL:
+
+1. Navigate to your DBNL deployment (e.g. http://localhost:8080/)
+2. Go to Projects > nat-calculator
+
+For additional help, see the [DBNL docs](https://docs.dbnl.com/).

examples/observability/simple_calculator_observability/README.md

@@ -251,6 +251,36 @@ Transmit traces to Galileo for workflow observability.
     nat run --config_file examples/observability/simple_calculator_observability/configs/config-galileo.yml --input "Is 100 > 50?"
     ```
 
+### Analyze Traces with DBNL
+
+[DBNL](https://www.distributional.com/) helps you understand your agent by analyzing your traces.
+
+1. Install DBNL:
+
+    Visit [https://docs.dbnl.com/get-started/quickstart](https://docs.dbnl.com/get-started/quickstart) to install DBNL.
+
+2. Create a trace ingestion project:
+
+    Navigate to your DBNL deployment and go to Projects > + New Project
+
+    Create a trace ingestion project and generate an API token
+
+    Take note of the API token and project id
+
+3. Set your DBNL credentials:
+
+    ```bash
+    # DBNL_API_URL should point to your deployment API URL (e.g. http://localhost:8080/api)
+    export DBNL_API_URL=<your_api_url>
+    export DBNL_API_TOKEN=<your_api_token>
+    export DBNL_PROJECT_ID=<your_project_id>
+    ```
+
+4. Run the workflow
+
+    ```bash
+    nat run --config_file examples/observability/simple_calculator_observability/configs/config-dbnl.yml --input "Is 100 > 50?"
+    ```
 
 ## Configuration Files
 
@@ -266,6 +296,7 @@ The example includes multiple configuration files for different observability pl
 | `config-patronus.yml` | Patronus | AI safety and compliance monitoring |
 | `config-catalyst.yml` | Catalyst | RagaAI Catalyst integration |
 | `config-galileo.yml` | Galileo | Galileo integration |
+| `config-dbnl.yml` | DBNL | AI product analytics |
 
 ## What Gets Traced
 

examples/observability/simple_calculator_observability/configs/config-dbnl.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+general:
+  telemetry:
+    logging:
+      console:
+        _type: console
+        level: WARN
+      file:
+        _type: file
+        path: ./.tmp/nat_simple_calculator.log
+        level: DEBUG
+    tracing:
+      dbnl:
+        _type: dbnl
+
+function_groups:
+  calculator:
+    _type: calculator
+
+functions:
+  current_datetime:
+    _type: current_datetime
+
+llms:
+  nim_llm:
+    _type: nim
+    model_name: meta/llama-3.1-70b-instruct
+    temperature: 0.0
+    max_tokens: 1024
+
+workflow:
+  _type: react_agent
+  tool_names: [calculator, current_datetime]
+  llm_name: nim_llm
+  verbose: true
+  parse_agent_response_max_retries: 3

packages/nvidia_nat_opentelemetry/src/nat/plugins/opentelemetry/register.py

@@ -193,3 +193,45 @@ async def galileo_telemetry_exporter(config: GalileoTelemetryExporter, builder:
         drop_on_overflow=config.drop_on_overflow,
         shutdown_timeout=config.shutdown_timeout,
     )
+
+
+class DBNLTelemetryExporter(BatchConfigMixin, TelemetryExporterBaseConfig, name="dbnl"):
+    """A telemetry exporter to transmit traces to DBNL."""
+
+    api_url: str | None = Field(description="The DBNL API URL.", default=None)
+    api_token: str | None = Field(description="The DBNL API token.", default=None)
+    project_id: str | None = Field(description="The DBNL project id.", default=None)
+
+
+@register_telemetry_exporter(config_type=DBNLTelemetryExporter)
+async def dbnl_telemetry_exporter(config: DBNLTelemetryExporter, builder: Builder):
+    """Create a DBNL telemetry exporter."""
+
+    from nat.plugins.opentelemetry import OTLPSpanAdapterExporter
+
+    api_token = config.api_token or os.environ.get("DBNL_API_TOKEN")
+    if not api_token:
+        raise ValueError("API token is required for DBNL")
+    project_id = config.project_id or os.environ.get("DBNL_PROJECT_ID")
+    if not project_id:
+        raise ValueError("Project id is required for DBNL")
+
+    headers = {
+        "Authorization": f"Bearer {api_token}",
+        "x-dbnl-project-id": project_id,
+    }
+
+    api_url = config.api_url or os.environ.get("DBNL_API_URL")
+    if not api_url:
+        raise ValueError("API url is required for DBNL")
+    endpoint = api_url.rstrip("/") + "/otel/v1/traces"
+
+    yield OTLPSpanAdapterExporter(
+        endpoint=endpoint,
+        headers=headers,
+        batch_size=config.batch_size,
+        flush_interval=config.flush_interval,
+        max_queue_size=config.max_queue_size,
+        drop_on_overflow=config.drop_on_overflow,
+        shutdown_timeout=config.shutdown_timeout,
+    )