# Observability

A copy of every request, as a trace, in your own monitoring tool.

1. [Pick the destination](#1-pick-the-destination).
2. [Add it](#2-add-it).
3. [Switch it on](#3-switch-it-on).

## 1. Pick the destination

A destination is where the traces go: a tool you already run, or any address that takes a webhook. Once it is added and on, every request a key sends is copied there as a trace.

| Destination | `type` | `config` needs |
|---|---|---|
| Arize AX | `arize` | `apiKey`, `spaceKey`, `modelId` |
| Braintrust | `braintrust` | `apiKey`, `projectId` |
| ClickHouse | `clickhouse` | `host`, `database`, `username`, `password` |
| Comet Opik | `opik` | `apiKey`, `workspace`, `projectName` |
| Datadog | `datadog` | `apiKey`, `mlApp` |
| Google BigQuery | `bigquery` | `projectId`, `serviceAccountKey` |
| Grafana Cloud | `grafana` | `apiKey`, `instanceId` |
| Langfuse | `langfuse` | `secretKey`, `publicKey` |
| LangSmith | `langsmith` | `apiKey` |
| New Relic | `newrelic` | `licenseKey` |
| OpenTelemetry | `otel-collector` | `endpoint` |
| PostHog | `posthog` | `apiKey` |
| Raindrop | `raindrop` | `writeKey` |
| Ramp | `ramp` | `apiKey` |
| S3 | `s3` | `bucketName`, `accessKeyId`, `secretAccessKey` |
| Sentry | `sentry` | `otlpEndpoint`, `dsn` |
| Snowflake | `snowflake` | `account`, `token` |
| W&B Weave | `weave` | `apiKey`, `entity`, `project` |
| a webhook | `webhook` | `url` |

The secrets in `config` are your tool's, never an OpenDunes key. Every read of a destination masks them.

## 2. Add it

Yacine wants Souk Bot's requests beside the rest of his logs. The sample adds a webhook destination, switched off, so nothing is sent before the address is his.

<div class="watch-out">
<p>The observability routes take a management key, never an API key. Set <code>OPENDUNES_MANAGEMENT_KEY</code> to your management key in the terminal that runs this sample. An API key gets a 401. See <a href="/docs/api-keys">API keys</a>.</p>
</div>

```python
import json
import os
import urllib.request

MANAGEMENT_KEY = os.environ["OPENDUNES_MANAGEMENT_KEY"]
base_url = "https://opendunes.com/v1"
webhook_url = "https://example.com/opendunes-traces"

destination = {
    "name": "Souk Bot logs",
    "type": "webhook",
    "config": {"url": webhook_url},
    "enabled": False,
}
request = urllib.request.Request(
    base_url + "/observability/destinations",
    data=json.dumps(destination).encode(),
    headers={
        "Authorization": "Bearer " + MANAGEMENT_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    added = json.load(response)["data"]

print(added["id"], added["enabled"])
```

```javascript
const MANAGEMENT_KEY = process.env.OPENDUNES_MANAGEMENT_KEY;
const baseURL = "https://opendunes.com/v1";
const webhookURL = "https://example.com/opendunes-traces";

const response = await fetch(`${baseURL}/observability/destinations`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MANAGEMENT_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Souk Bot logs",
    type: "webhook",
    config: { url: webhookURL },
    enabled: false,
  }),
});
if (!response.ok) {
  throw new Error(`${response.status} ${await response.text()}`);
}
const { data: destination } = await response.json();

console.log(destination.id, destination.enabled);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	managementKey := os.Getenv("OPENDUNES_MANAGEMENT_KEY")
	baseURL := "https://opendunes.com/v1"
	webhookURL := "https://example.com/opendunes-traces"

	body, err := json.Marshal(map[string]any{
		"name":    "Souk Bot logs",
		"type":    "webhook",
		"config":  map[string]string{"url": webhookURL},
		"enabled": false,
	})
	if err != nil {
		panic(err)
	}

	url := baseURL + "/observability/destinations"
	req, err := http.NewRequest("POST", url, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+managementKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		text, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("%d %s", res.StatusCode, text))
	}

	var answer struct {
		Data struct {
			ID      string `json:"id"`
			Enabled bool   `json:"enabled"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	fmt.Println(answer.Data.ID, answer.Data.Enabled)
}
```

```bash cURL
BASE_URL="https://opendunes.com/v1"
WEBHOOK_URL="https://example.com/opendunes-traces"

curl "$BASE_URL/observability/destinations" \
  -H "Authorization: Bearer $OPENDUNES_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Souk Bot logs",
    "type": "webhook",
    "config": {
      "url": "'"$WEBHOOK_URL"'"
    },
    "enabled": false
  }'
```

`201`, with the destination under `data` and its `id`.

| You send | Holds |
|---|---|
| `name` | your name for it |
| `type` | the destination, from the table above |
| `config` | what that destination needs |
| `enabled` | `true` to send traces, `false` to hold them |
| `api_key_hashes` | only the requests of these keys; every key when it is not sent |
| `sampling_rate` | the share of requests copied, from `0.0001` to `1` |
| `privacy_mode` | `true` to send the trace without the prompt and the answer |

<div class="watch-out">
<p>A trace carries the prompt and the answer, your customers' words included. To send it without them, set <code>privacy_mode</code> to <code>true</code>.</p>
</div>

## 3. Switch it on

Send your own address and `enabled` to `PATCH /v1/observability/destinations/{id}`. Only the fields you send change.

```json
{
  "config": {
    "url": "https://logs.souk-bot.example/opendunes"
  },
  "enabled": true
}
```

From then on, each request is copied there once it ends.

| Route | Does |
|---|---|
| `GET /v1/observability/destinations` | lists your destinations |
| `GET /v1/observability/destinations/{id}` | reads one, its secrets masked |
| `PATCH /v1/observability/destinations/{id}` | changes one |
| `DELETE /v1/observability/destinations/{id}` | removes one; nothing more is sent there |

Every observability route is free. Every field: [Trace destinations](/docs/reference/observability).

<div class="dont">
<p>Don't send a masked secret back: a masked value is ignored.</p>
</div>

<div class="do">
<p>Do send the new secret in full, inside <code>config</code>, to change it.</p>
</div>

## Errors

The body says why.

| Status | When |
|---|---|
| 400 | `type` is not in the table, or `config` lacks what that destination needs |
| 401 | the key is missing, wrong, disabled or expired, or it is an API key |
| 404 | no destination of yours has this `id` |
| 409 | your account holds as many destinations of this `type` as it can |

What to do on each: [Errors and retries](/docs/errors-and-retries).
