Log Trace

This API allows you to create a log trace with optional spans.

Request

Header

Authorization · string · required

Bearer Token Authentication

All API requests must include a valid workspace API key in the Authorization header using the Bearer token format.

Authorization: Bearer YOUR_WORKSPACE_API_KEY

You can create your workspace API key in Adaline by visiting Settings > API Keys.

Body

projectId · string · required

The unique identifier of the project in Adaline.

trace · object · required

The trace object containing trace details.

trace.startedAt · number · required

Unix timestamp when the trace started.

trace.endedAt · number

Unix timestamp when the trace ended (current time if not provided).

trace.name · string · required

Name/identifier for the trace.

trace.status · string · required

Status of the trace (one of: “success”, “failure”, “pending”, “unknown”).

trace.referenceId · string

External reference ID for the trace. This is usually the traceId used within your application / system.

trace.sessionId · string

Session ID associated with the trace. This is usually the sessionId / threadId / chatId used within your application / system.

trace.attributes · object

Additional attributes for the trace. Key-value pairs of attributes. Keys must be strings, values must be strings, numbers, or booleans.

trace.tags · array

Array of tags for categorization. Each tag must be a string.

spans · array

Array of span objects to create with the trace.

Span Object Parameters

promptId · string

The unique identifier of the prompt in Adaline.

deploymentId · string

The deployment ID of the prompt in Adaline.

startedAt · number · required

Unix timestamp when the span started.

endedAt · number · required

Unix timestamp when the span ended.

name · string · required

Name/identifier for the span.

status · string · required

Status of the span (one of: “success”, “failure”, “unknown”).

content · string · required

The stringified JSON content of the span (max 1MB). Refer Span Content.

runEvaluation · boolean

Whether to run evaluation on this span.

parentReferenceId · string

Reference ID of the parent span. This is usually the parent span’s spanId used within your application / system.

referenceId · string

External reference ID for the span. This is usually the spanId used within your application / system.

sessionId · string

Session ID associated with the span. This is usually the sessionId / threadId / chatId used within your application / system.

attributes · object

Additional attributes for the span. Key-value pairs of attributes. Keys must be strings, values must be strings, numbers, or booleans.

tags · array

Array of tags for categorization. Each tag must be a string.

Response

traceId · string

The unique identifier of the created trace.

spanIds · array

Array of unique identifiers for the created spans.

JavaScript

const API_KEY = "my_workspace_api_key";
const PROJECT_ID = "my_project_id";
const PROMPT_ID = "my_prompt_id";
const BASE_URL = "https://api.adaline.ai/v2/logs";

async function createLogTrace(trace, spans = []) {
  const response = await fetch(`${BASE_URL}/trace`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      projectId: PROJECT_ID,
      trace,
      spans,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error}`);
  }

  return response.json();
}

async function main() {
  try {
    const traceResult = await createLogTrace(
      {
        startedAt: Date.now(),
        endedAt: Date.now() + 60000,
        name: "user_interaction",
        status: "success",
        referenceId: "trace_001",
        sessionId: "session_123",
        attributes: {
          "app_name": "my_app",
          "user_id": "user_123"
        },
        tags: ["dev-env"]
      },
      [
        {
          promptId: PROMPT_ID,
          startedAt: Date.now(),
          endedAt: Date.now() + 30000,
          name: "llm_call",
          status: "success",
          content: {
            "type": "Model",
            "provider": "openai",
            "model": "gpt-4o-mini",
            "variables": {
              "user_input": {
                "modality": "text",
                "value": "librarian"
              }
            },
            "cost": 0.002,
            "input": "{\n    \"model\":\"gpt-4o-mini\",\n    \"max_tokens\": 50,\n    \"messages\": [{\n      \"role\": \"system\",\n      \"content\": [\n        {\n            \"type\": \"text\",\n            \"text\": \"You are a helpful librarian. You answer in 1-2 lines.\"\n        }\n      ]\n    },\n    {\n      \"role\": \"user\",\n      \"content\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"What is Adaline?\"\n        }\n      ]\n    }\n  ]\n}",
            "output": "{\n    \"id\": \"chatcmpl-BjKjQqVBN0WdTbkFHZ2C6tLXerKvl\",\n    \"object\": \"chat.completion\",\n    \"created\": 1750144152,\n    \"model\": \"gpt-4o-mini-2024-07-18\",\n    \"choices\": [\n        {\n            \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                \"content\": \"Adaline, or Adaptive Linear Neuron, is a type of artificial neural network that uses a linear activation function and employs the least mean squares (LMS) algorithm for training, aiming to minimize the difference between predicted and actual outputs.\",\n                \"refusal\": null,\n                \"annotations\": []\n            },\n            \"logprobs\": null,\n            \"finish_reason\": \"stop\"\n        }\n    ],\n    \"usage\": {\n        \"prompt_tokens\": 31,\n        \"completion_tokens\": 47,\n        \"total_tokens\": 78,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0,\n            \"audio_tokens\": 0\n        },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 0,\n            \"audio_tokens\": 0,\n            \"accepted_prediction_tokens\": 0,\n            \"rejected_prediction_tokens\": 0\n        }\n    },\n    \"service_tier\": \"default\",\n    \"system_fingerprint\": \"fp_34a54ae93c\"\n}"
          },
          referenceId: "span_001",
          sessionId: "session_123",
          attributes: {
            "app_name": "my_app",
            "user_id": "user_123"
          },
          tags: ["dev-env"]
        },
      ]
    );

    console.log("traceResult:", traceResult);
  } catch (error) {
    console.error("Error creating trace:", error);
  }
}

main();

200

{
  "traceId": "trace_abc123def456",
  "spanIds": ["span_xyz789ghi012"]
}

Trace Creation Validation Rules

1. Time Validation: startedAt must be before endedAt (if provided)
2. Span Time Validation: Each span’s startedAt must be before its endedAt
3. Trace-Span Time Relationship: All spans must start after or at the trace’s startedAt
4. Reference ID Uniqueness: All span referenceIds must be unique within the request
5. Parent Reference Validation: Any parentReferenceId must reference another span’s referenceId in the same request
6. Trace Reference Requirement: If any span has a referenceId, the trace must also have a referenceId

Best Practices

1. Structured Logging: Use consistent naming conventions for traces and spans to enable better analysis.

2. Reference IDs: Use meaningful reference IDs that can be tracked across your application for better debugging.

3. Content Size Management: Monitor your content size to stay within the 1MB limit per span.

4. Batch Operations: When possible, use the trace endpoint to create multiple spans in a single request.

5. Time Accuracy: Ensure timestamps are accurate and represent the actual start/end times of operations.

6. Meaningful Attributes: Use attributes and tags to add context that will be useful for analysis and debugging.

7. Session Tracking: Use session IDs consistently to track user sessions across multiple traces.