adaline-logs

Adaline Logs

Concepts

Adaline Logs provides structured observability for AI applications. Instrument any LLM call, tool execution, retrieval step, or custom operation and view it in the Adaline dashboard.

Key terms:

• Trace — an end-to-end request flow (e.g., one user turn in a chatbot, one agent run). Contains one or more spans.
• Span — a single operation within a trace (e.g., one LLM call, one tool invocation, one retrieval step). Spans can be nested using parentReferenceId.
• Session — a group of related traces (e.g., a multi-turn conversation or a batch job). Attach a sessionId to each trace.
• referenceId — a caller-supplied string ID for a trace or span, used for distributed tracing and deduplication.
• Content type — the semantic category of a span. One of: Model, ModelStream, Tool, Retrieval, Embeddings, Function, Guardrail, Other.

Content Types

Type	Use for
Model	Standard LLM chat/completion calls
ModelStream	Streaming LLM calls
Tool	Tool/function calls made by the model
Retrieval	Vector search, document lookup
Embeddings	Embedding generation
Function	Custom application logic
Guardrail	Content moderation, safety checks
Other	Anything else

Configuration

Set these environment variables when your Adaline credentials are available:

• ADALINE_API_KEY — your workspace API key (from Settings > API Keys at app.adaline.ai)
• projectId — your project ID (from the dashboard sidebar)
• Base URL: https://api.adaline.ai/v2

You can start integrating before you have credentials. All code examples use placeholder values — replace them with real values when ready.

Quick Start

Choose one approach based on your language and preference.

Approach 1: REST API (any language)

Create a trace with one span in a single call:

curl -X POST https://api.adaline.ai/v2/logs/trace \
  -H "Authorization: Bearer $ADALINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "trace": {
      "name": "chat-request",
      "status": "success",
      "startedAt": "2024-01-15T10:00:00.000Z",
      "endedAt": "2024-01-15T10:00:01.500Z"
    },
    "spans": [
      {
        "name": "gpt-4o-call",
        "status": "success",
        "startedAt": "2024-01-15T10:00:00.100Z",
        "endedAt": "2024-01-15T10:00:01.400Z",
        "content": {
          "type": "Model",
          "input": "{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}",
          "output": "{\"choices\":[{\"message\":{\"role\":\"assistant\",\"content\":\"Hi there!\"}}]}"
        }
      }
    ]
  }'

Response: { "traceId": "tr_abc123", "spanIds": ["sp_def456"] }

Approach 2: TypeScript SDK (@adaline/client)

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

const adaline = new Adaline({ apiKey: process.env.ADALINE_API_KEY });
const monitor = adaline.initMonitor({ projectId: 'your-project-id' });

// logTrace is synchronous — no await
const trace = monitor.logTrace({
  name: 'chat-request',
  status: 'unknown',
});

// ... run your LLM call ...

// logSpan is synchronous — no await
trace.logSpan({
  name: 'gpt-4o-call',
  status: 'success',
  content: {
    type: 'Model',
    input: JSON.stringify(openaiRequest),
    output: JSON.stringify(openaiResponse),
  } as LogSpanContent,
});

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

await monitor.flush(); // flush IS async

Approach 3: Python SDK (adaline-client)

import os
from adaline import Adaline

adaline = Adaline(api_key=os.environ["ADALINE_API_KEY"])
monitor = adaline.init_monitor(project_id="your-project-id")

trace = monitor.log_trace(name="chat-request")

span = trace.log_span(
    name="gpt-4o-call",
    content={
        "type": "Model",
        "input": json.dumps(openai_request),
        "output": json.dumps(openai_response),
    },
)
span.end(status="success")
trace.end(status="success")

monitor.flush()

Integration Patterns

Single-service logging

One service creates a trace and adds all its spans directly. Use monitor.logTrace() then trace.logSpan() for each operation.

Distributed tracing with referenceId

When multiple services contribute spans to a single logical trace:

1. Service A creates the trace with a referenceId (e.g., the request UUID)
2. Service B adds spans using traceReferenceId to find the trace without knowing the internal traceId

// Service A
monitor.logTrace({ name: 'orchestrator', referenceId: requestId, status: 'unknown' }); // SYNC

// Service B (later, different process)
const trace = monitor.logTrace({ name: 'retrieval-service', referenceId: requestId, status: 'unknown' });
trace.logSpan({
  name: 'retrieval-step',
  ...
});

Session tracking

Group related traces (e.g., turns in a conversation) under a sessionId:

monitor.logTrace({
  name: 'turn-3',
  sessionId: conversationId,
  status: 'unknown',
});

User feedback logging

Attach feedback after the fact using PATCH /v2/logs/trace:

curl -X PATCH https://api.adaline.ai/v2/logs/trace \
  -H "Authorization: Bearer $ADALINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "tr_abc123",
    "attributes": {
      "operations": [
        { "operation": "create", "key": "user_feedback", "value": "thumbs_up" }
      ]
    }
  }'

Nested spans

Use parentReferenceId to create span trees within a trace:

trace.logSpan({ name: 'agent-loop', referenceId: 'loop-1', status: 'unknown' });
trace.logSpan({ name: 'tool-call', parentReferenceId: 'loop-1', status: 'success' });
trace.logSpan({ name: 'llm-response', parentReferenceId: 'loop-1', status: 'success' });

Best Practices

1. Pass the exact provider request and response objects as JSON strings in input/output — Adaline parses them for token counts, model names, and prompt rendering
2. Always set startedAt and endedAt for accurate latency measurement — capture timestamps before and after the operation
3. Use referenceId for any distributed system where multiple services instrument the same trace
4. Use sessionId for multi-turn conversations so you can replay full sessions in the dashboard
5. Call monitor.flush() before process exit to ensure buffered spans are sent
6. Set status: 'failure' and include error details in output when operations fail — this enables error rate dashboards

References

See references/api.md for the full REST API reference with all request/response schemas. See references/typescript-sdk.md for the complete TypeScript SDK reference with content type builders. See references/python-sdk.md for the complete Python SDK reference with async support.