Autoblocks

JavaScript Tracer SDK

Install

npm install @autoblocks/client

AutoblocksTracer

The AutoblocksTracer class is used to send events to Autoblocks. It can be initialized without any arguments if your ingestion key is set as an environment variable named AUTOBLOCKS_INGESTION_KEY.

JavaScript

import { AutoblocksTracer } from '@autoblocks/client';

const tracer = new AutoblocksTracer();

Since an instance of AutoblocksTracer contains internal state, we recommend creating a new instance on each request or operation you are tracing.

Otherwise, you can pass the ingestion key as an argument:

JavaScript

const tracer = new AutoblocksTracer({
  ingestionKey: 'your-ingestion-key'
});

There are additional arguments that you can use to further configure the tracer:

  • Name
    traceId
    Type
    string | undefined
    Description

    The traceId for all events sent through the tracer instance.

  • Name
    properties
    Type
    object | undefined
    Description

    The properties that will be sent for all events sent through the tracer instance.

  • Name
    timeout
    Type
    object | undefined
    Description

    The timeout for each sendEvent call, which is a POST request to the Autoblocks ingestion API. Default value is { seconds: 5 }.

    The timeout property should be an object with the below schema:

    {
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
}

    You can use any combination of the above fields to express a timeout.

    For example:

    { hours: 1, minutes: 30 }

    Is the same as:

    { hours: 1.5 }

JavaScript

const tracer = new AutoblocksTracer({
  traceId: 'my-trace-id',
  properties: { source: 'my-app' },
  timeout: { seconds: 1 },
});

sendEvent

Send an event to Autoblocks.

JavaScript

tracer.sendEvent('ai.request', {
  properties: {
    provider: 'openai',
    prompt: 'Hello!',
  },
});

The sendEvent method is "fire and forget"; it will return immediately and the event will be sent in the background.

Arguments

  • Name
    message
    Type
    string
    Description

    The name of the event.

  • Name
    options
    Type
    object | undefined
    Description

    Optional object containing additional information about the event.

  • Name
    traceId
    Type
    string | undefined
    Description

    Used to group related events together. If not provided, defaults to a random UUID.

    • The traceId set within sendEvent takes precedence over a traceId that has been previously set.

    The order of precedence is:

    1. traceId set via sendEvent
    2. traceId set via setTraceId
    3. traceId set via the constructor
  • Name
    properties
    Type
    object | undefined
    Description

    Custom properties to attach to the event. The values in this object can be anything, including other objects.

    • The properties set within sendEvent take precedence over any other properties that have been set.

    The order of precedence is:

    1. properties set via sendEvent
    2. properties set via setProperties or updateProperties
    3. properties set via the constructor
  • Name
    spanId
    Type
    string | undefined
    Description

    Within a trace, connect related events together using span IDs. This is useful to connect request and response events together, for example.

  • Name
    parentSpanId
    Type
    string | undefined
    Description

    Establish parent / child relationships between your spans using parent span IDs. For example, if some events represent work being done on behalf of a higher level span in your trace, you should set that span's ID as the parent span ID for those events.

    • Read more about spans and the Trace Tree UI.

  • Name
    timestamp
    Type
    string | undefined
    Description

    An ISO date time string of when the event happened. If not provided, defaults to the current time.

setTraceId

Use this method to set the traceId for all subsequent calls of sendEvent.

JavaScript

tracer.setTraceId('my-trace-id');

Arguments

  • Name
    traceId
    Type
    string
    Description

    The traceId to set.

setProperties

Use this method to set the properties for all subsequent calls of sendEvent.

This method overwrites any existing properties that were previously set. If a property that already exists is not specified in the argument to setProperties, it will be removed.

JavaScript

tracer.setProperties({ x: 1, y: 2 }); // --> { x: 1, y: 2 }
tracer.setProperties({ x: 2 }); // --> { x: 2 }

Arguments

  • Name
    properties
    Type
    object
    Description

    The properties to set.

updateProperties

Use this method to update the properties for all subsequent calls of sendEvent.

This method merges any existing properties that were previously set. If a property already exists, it will be overwritten.

JavaScript

tracer.updateProperties({ x: 1, y: 2 }); // --> { x: 1, y: 2 }
tracer.updateProperties({ x: 2 }); // --> { x: 2, y: 2 }

Arguments

  • Name
    properties
    Type
    object
    Description

    The properties to update.