# Quickstart

### Determine how you’d like to explore DBNL

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

1. [Hosted Demo Account](#explore-the-product-with-a-read-only-saas-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](#deploy-a-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](https://github.com/dbnlAI/examples/tree/main?tab=readme-ov-file#getting-data-into-dbnl). After completing the Sandbox demo, you can explore how to instrument an agentic system and augment and upload the collected data via [this example](https://github.com/dbnlAI/examples/tree/main/adk_calculator_sdk_from_otel) in our Github.
4. [POC Environment with Your Data](https://docs.dbnl.com/platform/deployment). 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](https://docs.dbnl.com/workflow/projects#creating-a-project) 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](https://github.com/dbnlAI/examples) that update daily so that you can explore right away.

Go to [app.dbnl.com](https://app.dbnl.com/?organization=org_9fHaKKcmFZcdTkGw\&connection=Username-Password-Authentication\&login_hint=demo-user@distributional.com\&screen_hint=login)

* Username: `demo-user@distributional.com`
* Password: `dbnldemo1!`

### Deploy a Local Sandbox with Example Data

This guide walks you through using the DBNL [Sandbox](https://docs.dbnl.com/platform/deployment/sandbox) and [SDK Log Ingestion](https://docs.dbnl.com/configuration/data-connections/sdk-log-ingestion) using the [Python SDK](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk.md) to create your first project, submit log data to it, and start analyzing. See a 3 min walkthrough in our [overview video](https://www.youtube.com/watch?v=DfL-FcB5W6Q).

For more detailed walkthroughs see the [Tutorials](https://docs.dbnl.com/examples/tutorials).

{% stepper %}
{% step %}
**Get and install the latest DBNL SDK and Sandbox.**

{% hint style="warning" %}
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](https://docs.dbnl.com/platform/deployment/sandbox) docs.
{% endhint %}

```bash
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`
  {% endstep %}

{% step %}
**Create a Model Connection**

Every DBNL Project requires a [Model Connection](https://docs.dbnl.com/configuration/model-connections) 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](https://docs.dbnl.com/configuration/model-connections#creating-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](https://docs.dbnl.com/workflow/metrics) generation and [Insight](https://docs.dbnl.com/workflow/insights) generation as part of the [Data Pipeline](https://docs.dbnl.com/configuration/data-pipeline). We [suggest](https://docs.dbnl.com/configuration/model-connections#recommended-model-connections) cutting a new key with a budget and using a mid-weight model like GPT-OSS-20B.
   {% endstep %}

{% step %}
**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](https://github.com/dbnlAI/examples/tree/main/quickstart) in the [dbnlAI/examples](https://github.com/dbnlAI/examples) GitHub repository.

```python
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}")
```

{% hint style="info" %}
After uploading, the data pipeline will run automatically. Depending on the latency of your [Model Connection](https://docs.dbnl.com/configuration/model-connections), it may take several minutes to complete all steps (Ingest → Enrich → Analyze → Publish). Check the Status page to monitor progress.
{% endhint %}
{% endstep %}

{% step %}
**Discover, investigate, and track behavioral signals**

See a 3 min walkthrough in our [overview video](https://www.youtube.com/watch?v=DfL-FcB5W6Q).

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"

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}
{% endstepper %}

## Next Steps

* Create a Project with your own data using OTEL Trace or SDK ingestion with the [Data Connections](https://docs.dbnl.com/configuration/data-connections) guides.
* Learn more about the [Adaptive Analytics Workflow](https://docs.dbnl.com/workflow/adaptive-analytics-workflow).
* Deploy the full DBNL platform with the [Deployment](https://docs.dbnl.com/platform/deployment) options.
* Need help? Contact <support@distributional.com> or visit [distributional.com/contact](https://distributional.com/contact)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dbnl.com/get-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.