Log Trace

This API allows you to update an existing log trace properties such as status, end time, attributes, and tags.

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.

traceId · string

The unique identifier of the trace to update (required if referenceId not provided).

referenceId · string

The reference ID of the trace to update (required if traceIdnot provided).

logTrace · object · required

The trace update object containing fields to modify.

logTrace.status · string

New status of the trace (one of: “success”, “failure”, “pending”, “unknown”)

logTrace.endedAt · number

Unix timestamp when the trace ended

logTrace.attributes · array

Array of attribute operations to perform (max 10 operations).

logTrace.tags · array

Array of tag operations to perform (max 10 operations).

Attribute Operations

Each attribute operation in the attributes array must specify an operation type:

operation · string · required

Either “create” or “delete”.

key · string · required

The attribute key.

value · string/number/boolean

The attribute value (required for “create” operation).

Tag Operations

Each tag operation in the tags array must specify an operation type:

operation · string · required

Either “create” or “delete”.

tag · string · required

The tag value.

Response

success · boolean

Indicates if the update was successful.

JavaScript

const WORKSPACE_API_KEY = "your_workspace_api_key";
const BASE_URL = "https://api.adaline.ai/v2/logs";

// Update a log trace
async function updateLogTrace(projectId, traceId, referenceId, logTrace) {
  const requestBody = {
    projectId,
    logTrace,
  };

  // Add either traceId or referenceId
  if (traceId) {
    requestBody.traceId = traceId;
  } else if (referenceId) {
    requestBody.referenceId = referenceId;
  } else {
    throw new Error("Either traceId or referenceId must be provided");
  }

  const response = await fetch(`${BASE_URL}/update-log`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${WORKSPACE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(requestBody),
  });

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

  return response.json();
}

// Usage examples
try {
  // Update trace status and add completion metadata
  const updateResult1 = await updateLogTrace(
    "project_123",
    null, // traceId
    "trace_001", // referenceId
    {
      status: "success",
      endedAt: Date.now(),
      attributes: [
        {
          operation: "create",
          key: "totalDuration",
          value: 45000,
        },
        {
          operation: "create",
          key: "completionReason",
          value: "finished",
        },
      ],
      tags: [
        {
          operation: "create",
          tag: "completed",
        },
        {
          operation: "delete",
          tag: "processing",
        },
      ],
    }
  );

  console.log("Updated trace:", updateResult1.success);

  // Update only status
  const updateResult2 = await updateLogTrace(
    "project_123",
    "trace_xyz789", // traceId
    null, // referenceId
    {
      status: "failure",
      attributes: [
        {
          operation: "create",
          key: "errorReason",
          value: "timeout",
        },
      ],
    }
  );

  console.log("Updated trace status:", updateResult2.success);

  // Clean up temporary attributes
  const updateResult3 = await updateLogTrace(
    "project_123",
    null, // traceId
    "trace_002", // referenceId
    {
      attributes: [
        {
          operation: "delete",
          key: "tempProcessingData",
        },
        {
          operation: "delete",
          key: "debugInfo",
        },
      ],
    }
  );

  console.log("Cleaned up attributes:", updateResult3.success);
} catch (error) {
  console.error("Error:", error.message);
}

400

{
  "error": "<bad request error details...>"
}

Validation Rules

1. Trace Identification: Either traceId or referenceId must be provided (but not both)
2. Required Fields: At least one field in logTrace must be provided for update
3. Time Validation: If endedAt is provided, it must be after the original trace’s startedAt
4. Attribute Operations Limit: Maximum of 10 attribute operations per request
5. Tag Operations Limit: Maximum of 10 tag operations per request
6. Attribute Values: For “create” operations, the value field is required and must be a string, number, or boolean
7. Operation Types: Only “create” and “delete” operations are supported for attributes and tags

Common Use Cases

1. Finalizing Trace Status

Update a trace from “pending” to final status after processing completes:

JavaScript

await updateLogTrace("project_123", null, "trace_ref_001", {
  status: "success",
  endedAt: Date.now(),
  attributes: [
    {
      operation: "create",
      key: "completionTime",
      value: Date.now(),
    },
  ],
});

2. Error Handling

Mark a trace as failed and add error information:

JavaScript

await updateLogTrace("project_123", "trace_id_123", null, {
  status: "failure",
  endedAt: Date.now(),
  attributes: [
    {
      operation: "create",
      key: "errorCode",
      value: "PROCESSING_ERROR",
    },
    {
      operation: "create",
      key: "errorMessage",
      value: "Failed to process due to invalid input",
    },
  ],
  tags: [
    {
      operation: "create",
      tag: "error",
    },
  ],
});

3. Adding Metrics

Add performance metrics after processing:

Python

update_log_trace(
    'project_123',
    reference_id='perf_trace_001',
    log_trace={
        'attributes': [
            {
                'operation': 'create',
                'key': 'responseTime',
                'value': 1.25
            },
            {
                'operation': 'create',
                'key': 'tokensProcessed',
                'value': 500
            },
            {
                'operation': 'create',
                'key': 'qualityScore',
                'value': 0.92
            }
        ]
    }
)

Best Practices

1. Batch Updates: Combine multiple attribute and tag operations in a single request to reduce API calls.

2. Final Status Updates: Always update the trace status to a final state (“success”, “failure”) when processing completes.

3. Consistent Tagging: Use consistent tag naming conventions for better categorization and filtering.

4. Meaningful Attributes: Add attributes that provide valuable context for analysis and troubleshooting.