Get started
Loading documentation…
Datool DocsDatool DocsTrace an AI SDK call, a TypeScript or Python function, or a LangGraph application.
Record your first trace using the library you already work with. Start with an AI SDK model call, or choose TypeScript, Python, or LangGraph below.
You need a running Datool instance and access to a project. If you are running Datool yourself, complete self-hosting setup first, including the ingestion worker.
Open Datool and sign in. Select an organization and project, or create them if your role permits it.
In Project settings, copy the project ID. Use the ID rather than the project slug from the browser address. Open Project settings → API keys and create an organization API key with traces:write. An organization owner or admin can create a key for you. Copy it when it is shown.
Create a .env file with your instance URL, project ID, and API key. Replace the example values and keep the file out of version control.
DATOOL_BASE_URL=https://your-datool-host
DATOOL_PROJECT_ID=your-project-id
DATOOL_API_KEY=your-api-keyUse http://localhost:3000 for a local Datool installation. The base URL is the application origin; do not append /api.
Each tab includes installation, a complete script, and a run command. The Node examples require Node.js 22.18 or later. The Python examples require Python 3.10 or later and access to the preview SDK wheel.
AI SDK 7 — trace a model call
Install the SDK and telemetry integration:
npm install @datool/sdk@0.3.1 ai@7 @ai-sdk/otel @opentelemetry/api@1 @opentelemetry/sdk-trace-node@2Add your Vercel AI Gateway key to .env:
AI_GATEWAY_API_KEY=your-ai-gateway-keyThis example makes a real model call and incurs provider usage. Save first-trace.mjs. After the one-time telemetry setup, use generateText normally:
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"
import { generateText, registerTelemetry } from "ai"
import { LegacyOpenTelemetry } from "@ai-sdk/otel"
import { DatoolSpanProcessor } from "@datool/sdk/otel"
const processor = new DatoolSpanProcessor()
const provider = new NodeTracerProvider({ spanProcessors: [processor] })
provider.register()
registerTelemetry(new LegacyOpenTelemetry())
try {
const result = await generateText({
model: "openai/gpt-4.1-mini",
prompt: "Explain AI observability in one sentence.",
telemetry: { functionId: "docs-greeting" },
})
console.log(result.text)
} finally {
try {
await processor.forceFlush()
} finally {
await provider.shutdown()
}
}node --env-file=.env first-trace.mjsExpect a generated sentence. In Datool, find the latest docs-greeting call and inspect its nested model span for the prompt, response, model, and provider-reported token usage. See the AI SDK guide for streaming, existing OpenTelemetry setups, and AI SDK 6.
Open Traces in the same project, select the new trace, and inspect its inputs, outputs, duration, and status. For model calls, select the nested LLM span to inspect model details and token usage. The Python function and deterministic graph examples have no token usage.
The scripts flush before exiting so delivery failures are visible. In a long-running application, configure tracing once at startup and flush during graceful shutdown.
| Symptom | What to check |
|---|---|
| HTTP 401 | The key is valid, has not expired, and belongs to this instance. |
| HTTP 403 | The key grants traces:write and its organization owns the project. |
| Model-provider authentication error | The AI Gateway or OpenAI key is configured separately from the Datool key. |
| Connection error | The base URL is reachable from the process running the script. |
| Pending or timed-out delivery | Redis and the ingestion worker are running; inspect worker logs. |
| Script succeeds but the list looks empty | Select the same project and clear restrictive date or collection filters. |
Next, run your first evaluation or use a managed prompt. For custom spans and application-level grouping, see manual instrumentation.