Adaline Logs

Concepts

Adaline Logs captures AI application execution as traces and spans.

Key terms:

• Trace — one end-to-end user request, agent run, job, or conversation turn
• Span — one operation inside a trace, such as an LLM call or retrieval step
• referenceId — caller-supplied ID for stitching traces/spans across services
• sessionId — groups related traces, such as a chat thread
• Content type — semantic span payload: Model, ModelStream, Tool, Retrieval, Embeddings, Function, Guardrail, or Other

Configuration

Set these environment variables when credentials are available:

• ADALINE_API_KEY — workspace API key from Admin > API Keys
• ADALINE_PROJECT_ID — project ID

Base URL: https://api.adaline.ai/v2

Quick Start

TypeScript SDK

import { Adaline } from '@adaline/client';
import type { LogSpanContent } from '@adaline/api';

const adaline = new Adaline();
const monitor = adaline.initMonitor({ projectId: process.env.ADALINE_PROJECT_ID! });

const trace = monitor.logTrace({ name: 'chat-request', sessionId: 'user_42' });

const span = trace.logSpan({
  name: 'llm-call',
  status: 'unknown',
});

// Run provider call here.

span.update({
  status: 'success',
  content: {
    type: 'Model',
    provider: 'openai',
    model: 'gpt-4o',
    input: JSON.stringify(openaiRequest),
    output: JSON.stringify(openaiResponse),
  } as LogSpanContent,
});
span.end();

trace.update({ status: 'success' });
trace.end();

await monitor.flush();
monitor.stop();

Python SDK

import json
from adaline import Adaline
from adaline_api.models.log_span_content import LogSpanContent
from adaline_api.models.log_span_model_content import LogSpanModelContent

adaline = Adaline()
monitor = adaline.init_monitor(project_id="project_abc123")

trace = monitor.log_trace(name="chat-request", session_id="user_42")
span = trace.log_span(name="llm-call", status="unknown")

# Run provider call here.

span.update({
    "status": "success",
    "content": LogSpanContent(LogSpanModelContent(
        type="Model",
        provider="openai",
        model="gpt-4o",
        input=json.dumps(openai_request),
        output=json.dumps(openai_response),
    )),
})
span.end()

trace.update({"status": "success"})
trace.end()

await monitor.flush()
monitor.stop()

REST API

curl -X POST "https://api.adaline.ai/v2/logs/trace" \
  -H "Authorization: Bearer $ADALINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_abc123",
    "trace": {
      "name": "chat-request",
      "status": "success",
      "referenceId": "request-123",
      "startedAt": 1713657600000,
      "endedAt": 1713657602500
    },
    "spans": [
      {
        "name": "llm-call",
        "status": "success",
        "referenceId": "span-123",
        "startedAt": 1713657600100,
        "endedAt": 1713657602400,
        "content": {
          "type": "Model",
          "provider": "openai",
          "model": "gpt-4o",
          "input": "{\"messages\":[]}",
          "output": "{\"choices\":[]}"
        }
      }
    ]
  }'

Integration Patterns

Single-service logging

Use the SDK monitor. Create a trace, create spans from that trace, call end(), then flush before process exit.

Nested spans

const parent = trace.logSpan({ name: 'agent-loop', referenceId: 'loop-1' });
const child = parent.logSpan({ name: 'tool-call' });
child.end();
parent.end();

parent = trace.log_span(name="agent-loop", reference_id="loop-1")
child = parent.log_span(name="tool-call")
child.end()
parent.end()

Distributed tracing

Use REST POST /logs/span or raw SDK logsApi/logs_api with traceReferenceId / trace_reference_id when a different process needs to attach a span to an existing trace.

User feedback and trace metadata

Use PATCH /logs/trace with logTrace.attributes and logTrace.tags operation arrays.

Best Practices

1. Store provider request/response bodies as JSON strings in span input and output.
2. Use referenceId on traces and spans so distributed systems can stitch work together.
3. Use sessionId for multi-turn chats or long-running workflows.
4. End spans before ending traces; trace end will also end child spans as a safety net.
5. Await monitor.flush() in Python and TypeScript before shutdown/serverless return.
6. In Python, pass generated LogSpanContent(...) wrapper objects, not raw dictionaries, for SDK span content.

References

See references/api.md for REST payloads. See references/typescript-sdk.md for TypeScript SDK usage. See references/python-sdk.md for Python SDK usage.