Ctrlk
SupportAboutBlogLaunch app ↗
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Quickstart

Start analyzing with the DBNL platform immediately

Determine how you’d like to explore DBNL

We’ve made it easy to get started exploring DBNL in a variety of ways:

  1. Hosted Demo Account. Start here if you want to start exploring the DBNL product with pre-populated data in a hosted environment. You won’t have to deploy anything but you also won’t see how data is ingested in the product.

  2. Local Sandbox with Example Data. Start here to install the DBNL SDK and Sandbox locally to create your first project, submit log data to it, and start analyzing. Technical users that want to roll up their sleeves but don’t have project data to work with can start here.

  3. Advanced Data Collection Examples. After completing the Sandbox demo, you can explore how to instrument an agentic system and augment and upload the collected data via this example in our Github.

  4. POC Environment with Your Data. If you would like to start building a POC project using your own data via OTEL Trace Ingestion or SDK Log Ingestion, start with the full Project Setup docs. Getting going will take longer but you’ll cover more of the fundamentals and have a more robust foundation for future development.

Explore the Product with a Read Only SaaS Account

You can start clicking around the product right away in a pre-provisioned Read Only SaaS account. This organization has pre-populated Projects from our Examples Repo that update daily so that you can explore right away.

Go to app.dbnl.com

  • Username: demo-user@distributional.com

  • Password: dbnldemo1!

Deploy a Local Sandbox with Example Data

This guide walks you through using the DBNL Sandbox and SDK Log Ingestion using the Python SDK to create your first project, submit log data to it, and start analyzing. See a 3 min walkthrough in our overview video.

For more detailed walkthroughs see the Tutorials.

1

Get and install the latest DBNL SDK and Sandbox.

The Sandbox runs inside a Docker container and spins up a k3d cluster within it. For more information and full requirements check out the Sandbox Deployment docs.

pip install --upgrade dbnl
dbnl sandbox start
dbnl sandbox logs # See spinup progress

Log into the sandbox at http://localhost:8080 using

  • Username: admin

  • Password: password

2

Create a Model Connection

Every DBNL Project requires a Model Connection to create LLM-as-judge metrics and perform analysis.

  1. Click on the "Model Connections" tab on the left panel of http://localhost:8080

  2. Click "+ Add Model Connection"

  3. Create a Model Connection with the name: quickstart_model . After selecting a provider you will be prompted to enter an API Key and model name, this model will be used for Metric generation and Insight generation as part of the Data Pipeline. We suggest cutting a new key with a budget and using a mid-weight model like GPT-OSS-20B.

3

Create a project and upload example data using the SDK

This example uses real LLM conversation logs from an "Outing Agent" application. The data is publicly available in S3.

You can grab the code from the Quickstart Example in the dbnlAI/examples GitHub repository.

import dbnl
import io, json, zstandard, pandas
from datetime import datetime, timedelta, timezone
from urllib.request import urlopen

print("dbnl version:", dbnl.__version__)

dbnl.login(
    api_url="http://localhost:8080/api",
    api_token="",  # found at http://localhost:8080/tokens
)

project = dbnl.get_or_create_project(
    name="Quickstart Demo",
    default_llm_model_name="quickstart_model",  # from step (2) above
)

# Load 14 days of OTEL traces from public S3 and upload to DBNL
BASE = "https://dbnl-demo-public.s3.us-east-1.amazonaws.com/outing_agent_log_data"
today = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
dctx = zstandard.ZstdDecompressor()

print(f"See status at: {dbnl.config.app_url()}/ns/{project.namespace_id}/projects/{project.id}/status")
for i in range(14):
    data_start = today - timedelta(days=14 - i)
    data_end = data_start + timedelta(days=1)
    day = data_start.strftime("%Y-%m-%d")
    try:
        raw = dctx.stream_reader(io.BytesIO(urlopen(f"{BASE}/traces_{day}.jsonl.zst").read())).read()
        data = pandas.Series([json.loads(l) for l in raw.decode().splitlines()])
        print(f"[{i+1}/14] {day}: uploading {len(data)} records")
    except Exception as e:
        if "Not Found" in str(e):
            print(f"[{i+1}/14] {day}: no data")
            continue
        raise
    try:
        dbnl.log(
            project_id=project.id,
            data_start_time=data_start,
            data_end_time=data_end,
            otlp_data=data,
            wait_timeout=60 * 30,
        )
    except Exception as e:
        if "Data already exists" in str(e):
            print(f"[{i+1}/14] {day}: data already exists")
            continue
        raise
print(f"Explore: {dbnl.config.app_url()}/ns/{project.namespace_id}/projects/{project.id}")

After uploading, the data pipeline will run automatically. Depending on the latency of your Model Connection, it may take several minutes to complete all steps (Ingest → Enrich → Analyze → Publish). Check the Status page to monitor progress.

4

Discover, investigate, and track behavioral signals

See a 3 min walkthrough in our overview video.

After the data processing completes (check the Status page):

  1. Go back to the DBNL project at http://localhost:8080

  2. Discover your first behavioral signals by clicking on "Insights"

  3. Investigate these insights by clicking on the "Explorer" or "Logs" button

  4. Track interesting patterns by clicking "Add Segment to Dashboard"

No Insights appearing? The system needs at least 7 days of data to establish behavioral baselines. If you just uploaded data, check the Status page to ensure all pipeline steps (Ingest → Enrich → Analyze → Publish) completed successfully.

Next Steps

PreviousOverview - DBNLNextData Pipeline