Log Span

Request

Authorization

string

required

Bearer Token AuthenticationAll 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.

span

object

required

The span object containing span details.

span.startedAt

number

required

Unix timestamp when the span started.

span.endedAt

number

required

Unix timestamp when the span ended.

span.name

string

required

Name/identifier for the span.

span.status

string

required

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

span.content

object

required

The content object is a discriminated union based on the type field that determines the structure. Supported types include:

Model Type

For AI model interactions (LLM calls, completions, etc.):

{
  "type": "Model",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "variables": {
    "user_input": {
      "modality": "text",
      "value": "librarian"
    }
  },
  "cost": 0.002,
  "input": "{\"messages\": [{\"role\": \"user\", \"content\": [{\"modality\": \"text\", \"value\": \"You are a helpful {{user_input}}. You answer in 1-2 lines.\"}]}]}",
  "output": "{\"messages\": [{\"role\": \"assistant\", \"content\": [{\"modality\": \"text\", \"value\": \"Hello! How can I help you today?\"}]}]}",
}

Required Fields:

type: String identifying the span type
provider: String identifying the provider of the model
model: String identifying the model
input: JSON string containing input data, either exactly the payload sent to the LLM provider (using REST API) or using Adaline types.
output: JSON string containing output data, either exactly the response received from the LLM provider (using REST API) or using Adaline types.

If using Adaline types:

input.messages: refer to MessageType.
input.config: refer to ConfigType.
input.tools: refer to ToolType.

If using Adaline types:

output.messages: refer to MessageType.
output.tokenUsage.promptTokens: Number of tokens used for the prompt.
output.tokenUsage.completionTokens: Number of tokens used for the completion.
output.tokenUsage.totalTokens: Total number of tokens used.

If using LLM provider REST API payload, refer this example using OpenAI chat completion API payload:

{
  "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}"
}

Optional Fields:

cost: Number representing the cost of the span (in USD)
variables: JSON object containing variable values. key is the variable name and value is the variable value of type ContentType.

ModelStream Type

For streaming AI model interactions where responses come in chunks:It is recommended to have a parent span of type ‘Model’ for all ‘ModelStream’ spans. This will help you to view the complete response, time-to-first-token, etc. in the Monitor section. To achieve this, set parentReferenceId for each ‘ModelStream’ span to the parent span’s referenceId.

Chunk Span Example

{
  "type": "ModelStream",
  "provider": "openai",
  "model": "gpt-4",
  "input": "{\"messages\": [{\"role\": \"system\", \"content\": [{\"modality\": \"text\", \"value\": \"You are a creative storyteller.\"}]}, {\"role\": \"user\", \"content\": [{\"modality\": \"text\", \"value\": \"Write a short story about a robot discovering emotions\"}]}], \"stream\": true}",
  "output": "data: {\"id\":\"chatcmpl-xyz\",\"object\":\"chat.completion.chunk\",\"created\":1750144152,\"model\":\"gpt-4\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"golden fingers\"},\"finish_reason\":null}]}",
  "aggregateOutput": "{\"messages\": [{\"role\": \"assistant\", \"content\": [{\"modality\": \"text\", \"value\": \"As the dawn stretched its golden fingers\"}]}], \"chunk_metadata\": {\"chunk_size\": 13, \"time_from_start_ms\": 6730, \"accumulated_tokens\": 8}}"
}

Required Fields for ModelStream:

type: Must be “ModelStream”
provider: String identifying the provider of the model
model: String identifying the model
input: JSON string containing input data, either exactly the payload sent to the LLM provider (using REST API) or using Adaline types.
output: String containing the streaming response chunk.
aggregateOutput: JSON string containing the accumulated response up to this chunk.

Function Type

For function calls and executions:

{
  "type": "Function",
  "input": "{\"function_name\": \"calculate_sum\", \"args\": [1, 2, 3]}",
  "output": "{\"result\": 6}"
}

Tool Type

For tool usage and API calls:

{
  "type": "Tool",
  "input": "{\"tool\": \"weather_api\", \"location\": \"San Francisco\"}",
  "output": "{\"temperature\": 72, \"condition\": \"sunny\"}"
}

Guardrail Type

For safety and validation checks:

{
  "type": "Guardrail",
  "input": "{\"content\": \"User message to validate\", \"rules\": [\"no_pii\", \"content_safety\"]}",
  "output": "{\"passed\": true, \"violations\": []}"
}

Retrieval Type

For document retrieval and search operations:

{
  "type": "Retrieval",
  "input": "{\"query\": \"machine learning best practices\", \"top_k\": 5}",
  "output": "{\"documents\": [{\"id\": \"doc1\", \"score\": 0.95, \"content\": \"...\"}]}"
}

Embeddings Type

For text embedding operations:

{
  "type": "Embeddings",
  "input": "{\"text\": \"Convert this text to embeddings\", \"model\": \"text-embedding-ada-002\"}",
  "output": "{\"embeddings\": [0.1, 0.2, 0.3, ...], \"dimensions\": 1536}"
}

Other Type

For custom span types not covered by the predefined categories:

{
  "type": "Other",
  "input": "{\"custom_field\": \"value\"}",
  "output": "{\"result\": \"success\"}"
}

Required Fields (for all span types other than ‘Model’):

type: String identifying the span type
input: JSON string containing input data
output: JSON string containing output data

Notes:

Maximum content size is 1MB

span.traceId

string

The ID of an existing trace (required if traceReferenceId not provided).

span.traceReferenceId

string

The reference ID of an existing trace (required if traceId not provided). This is usually the traceId used within your application / system.

span.promptId

string

The unique identifier of the prompt used. If not provided, you will not be able to view the span in prompt’s monitor section.

span.deploymentId

string

The deployment ID used for this span.

span.runEvaluation

boolean

Whether to run evaluation on this span.

span.parentReferenceId

string

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

span.referenceId

string

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

span.sessionId

string

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

span.attributes

object

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

span.tags

array

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

Response

spanId

array

Array of unique identifiers for the created span.

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

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

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

  return response.json();
}

async function main() {
  try {
    const spanResult = await createLogSpan({
      promptId: PROMPT_ID,
      traceId: TRACE_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_004",
      sessionId: "session_123",
      attributes: {
        "app_name": "my_app",
        "user_id": "user_123"
      },
      tags: ["dev-env"]
    });

    console.log("spanResult:", spanResult);
  } catch (error) {
    console.error("Error creating span:", error);
  }
}

main();

{
  "spanId":"5066102c-f90a-4a36-9cf0-4ea7759107b8"
}

Span Creation Validation Rules

Trace Association: Either traceId or traceReferenceId must be provided
Time Validation: startedAt must be before endedAt
Content Size: Content must not exceed 1MB when serialized to JSON

Best Practices

Structured Logging: Use consistent naming conventions for traces and spans to enable better analysis.
Reference IDs: Use meaningful reference IDs that can be tracked across your application for better debugging.
Content Size Management: Monitor your content size to stay within the 1MB limit per span.
Batch Operations: When possible, use the trace endpoint to create multiple spans in a single request.
Time Accuracy: Ensure timestamps are accurate and represent the actual start/end times of operations.
Meaningful Attributes: Use attributes and tags to add context that will be useful for analysis and debugging.
Session Tracking: Use session IDs consistently to track user sessions across multiple traces.

Reference

Types

API

Request

Header

Body

Model Type

ModelStream Type

Chunk Span Example

Function Type

Tool Type

Guardrail Type

Retrieval Type

Embeddings Type

Other Type

Response

Span Creation Validation Rules

Best Practices

Reference

Types

API

​Request

​Header

​Body

​Model Type

​ModelStream Type

​Chunk Span Example

​Function Type

​Tool Type

​Guardrail Type

​Retrieval Type

​Embeddings Type

​Other Type

​Response

​Span Creation Validation Rules

​Best Practices

Request

Header

Body

Model Type

ModelStream Type

Chunk Span Example

Function Type

Tool Type

Guardrail Type

Retrieval Type

Embeddings Type

Other Type

Response

Span Creation Validation Rules

Best Practices