# Trace destinations

`POST /v1/observability/destinations` adds a destination: a monitoring tool of yours that
receives a copy of every request, as a trace; five routes add, list, read, change and remove them.

## Request

Send them with a management key: set `OPENDUNES_MANAGEMENT_KEY` to it for these calls. An API
key gets a 401. The [Observability](/docs/observability) guide adds one from start to end.

| Route | Does |
|---|---|
| `POST /v1/observability/destinations` | adds a destination |
| `GET /v1/observability/destinations` | lists your destinations |
| `GET /v1/observability/destinations/{id}` | answers one |
| `PATCH /v1/observability/destinations/{id}` | changes one |
| `DELETE /v1/observability/destinations/{id}` | removes one; its traces stop |

### Add

`PATCH` takes the same fields but `type`; the `config` it sends is merged into the one kept.

| Field | Needed | You send |
|---|---|---|
| `name` | yes | a name of your own, up to 200 characters |
| `type` | yes | the tool, below; at most 5 destinations of one type |
| `config` | yes | the tool's settings, each a string, below. Every type also takes `headers`, sent with each trace. An address must be `https` and public |
| `enabled` | no | `false` to stop sending without removing it; absent, `true` |
| `privacy_mode` | no | `true` to leave the prompt and the answer out of each trace |
| `sampling_rate` | no | the share of requests sent, from 0.0001 to 1; absent, 1, every request |
| `api_key_hashes` | no | only the requests of these keys, each by its `hash`; absent, every key |
| `filter_rules` | no | only the requests that match: `{"groups": [{"logic": "and", "rules": [{"field": ..., "operator": ..., "value": ...}]}]}` |
| `broadcast_generation_cost` | no | `true` to put the request's charge in the trace |
| `broadcast_generation_identity` | no | `true` to put who sent it in the trace |
| `broadcast_generation_request_context` | no | `true` to put the request's context in the trace |
| `regions` | no | where traces leave from, a list of `global`, `europe` or `us`; absent, `["global"]` |

A rule's `field` is `model`, `provider`, `session_id`, `user_id`, `api_key_name`,
`finish_reason`, `input`, `output`, `total_cost`, `total_tokens`, `prompt_tokens` or
`completion_tokens`. Its `operator` is `equals`, `not_equals`, `contains`, `not_contains`,
`regex`, `starts_with`, `ends_with`, `gt`, `lt`, `gte`, `lte`, `exists` or `not_exists`.

| `type` | `config` needs | and may take |
|---|---|---|
| `arize` | `apiKey`, `spaceKey`, `modelId` | `baseUrl` |
| `braintrust` | `apiKey`, `projectId` | `baseUrl` |
| `clickhouse` | `host`, `database`, `username`, `password` | `table` |
| `datadog` | `apiKey`, `mlApp` | `url` |
| `bigquery` | `projectId`, `serviceAccountKey`, the service account's JSON key | `dataset`, `table` |
| `grafana` | `apiKey`, `instanceId` | `baseUrl` |
| `langfuse` | `secretKey`, `publicKey` | `baseUrl` |
| `langsmith` | `apiKey` | `endpoint`, `project`, `workspaceId` |
| `newrelic` | `licenseKey` | `region`, `us` or `eu` |
| `opik` | `apiKey`, `workspace`, `projectName` | — |
| `otel-collector` | `endpoint` | — |
| `posthog` | `apiKey` | `endpoint` |
| `raindrop` | `writeKey` | `baseUrl` |
| `ramp` | `apiKey` | `baseUrl` |
| `s3` | `bucketName`, `accessKeyId`, `secretAccessKey` | `endpoint`, `region`, `prefix`, `pathTemplate`, `sessionToken` |
| `sentry` | `otlpEndpoint`, `dsn` | — |
| `snowflake` | `account`, `token` | `database`, `schema`, `table`, `warehouse` |
| `weave` | `apiKey`, `entity`, `project` | `baseUrl` |
| `webhook` | `url` | `method`, `POST` or `PUT` |

Souk Bot sends every request to its Langfuse project, prompts left out.

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

MANAGEMENT_KEY = os.environ["OPENDUNES_MANAGEMENT_KEY"]
ADDRESS = "https://opendunes.com/v1/observability/destinations"

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "name": "Souk Bot traces",
            "type": "langfuse",
            "config": {
                "publicKey": os.environ["LANGFUSE_PUBLIC_KEY"],
                "secretKey": os.environ["LANGFUSE_SECRET_KEY"],
            },
            "privacy_mode": True,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + MANAGEMENT_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    destination = json.load(response)["data"]

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

```javascript
const MANAGEMENT_KEY = process.env.OPENDUNES_MANAGEMENT_KEY;
const ADDRESS = "https://opendunes.com/v1/observability/destinations";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MANAGEMENT_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Souk Bot traces",
    type: "langfuse",
    config: {
      publicKey: process.env.LANGFUSE_PUBLIC_KEY,
      secretKey: process.env.LANGFUSE_SECRET_KEY,
    },
    privacy_mode: true,
  }),
});
const { data } = await response.json();

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

```go
package main

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

const address = "https://opendunes.com/v1/observability/destinations"

func main() {
	managementKey := os.Getenv("OPENDUNES_MANAGEMENT_KEY")

	body, err := json.Marshal(map[string]any{
		"name": "Souk Bot traces",
		"type": "langfuse",
		"config": map[string]string{
			"publicKey": os.Getenv("LANGFUSE_PUBLIC_KEY"),
			"secretKey": os.Getenv("LANGFUSE_SECRET_KEY"),
		},
		"privacy_mode": true,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, 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()

	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
ADDRESS="https://opendunes.com/v1/observability/destinations"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Souk Bot traces",
    "type": "langfuse",
    "config": {
      "publicKey": "'"$LANGFUSE_PUBLIC_KEY"'",
      "secretKey": "'"$LANGFUSE_SECRET_KEY"'"
    },
    "privacy_mode": true
  }'
```

### List

`GET /v1/observability/destinations` takes its fields in the address, after `?`.

| Field | Needed | You send |
|---|---|---|
| `limit` | no | how many one page holds, 1 to 100; absent, 50 |
| `offset` | no | how many to skip, for the next page |

## Response

`POST` answers `201 Created` with `data`, the destination; `GET` and `PATCH` on one answer
`200 OK` with the same. The list answers `data`, a list, and `total_count`.

| Field | Holds |
|---|---|
| `data` | the destination, or the list |
| `total_count` | on a list: how many there are in all |
| `id` | the destination's id |
| `name` · `type` | as you set them |
| `config` | its settings, each secret shown as its first and last four characters only |
| `enabled` · `privacy_mode` · `sampling_rate` · `api_key_hashes` · `filter_rules` · `regions` | as you set them, or their defaults |
| `broadcast_generation_cost` · `broadcast_generation_identity` · `broadcast_generation_request_context` | as you set them |
| `created_at` · `updated_at` | when it was added and last changed, in UTC |

`DELETE` answers `200 OK` with `deleted`, `true`.

## What it cost

Free. Adding and running a destination is never charged; the requests it copies are charged as
they always are.

## Errors

`error.code` carries the status, and `error.message` says why.

| Status | When |
|---|---|
| 400 | `name`, `type` or `config` is missing, `type` is not one of the tools, `config` lacks a setting the tool needs or holds one it does not take, an address is not public `https`, or `type` is sent on a change; `error.metadata.errors` names the field |
| 401 | the management key is missing, wrong, revoked or expired, or it is an API key |
| 404 | no destination of yours has that `id` |
| 409 | you already have 5 destinations of that type |
