tctx/traceparent.d.mts

W3C Trace Contexts made simple

/**
* A simple implementation of the {@link https://www.w3.org/TR/trace-context-2/|W3C Trace Context specification level 2}.
*
* This module provides a simple API for creating, parsing, and manipulating traceparent headers.
*
* The anatomy of a traceparent:
*
* ```
* 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
* ^  ^                                ^                ^
* |  |                                |                |
* |  |                                |                flags (2 hex)
* |  |                                parent-id (16 hex)
* |  trace-id (32 hex)
* version (2 hex)
* ```
*
* @example
* ```ts
* let traceparent = parse(req.headers.get('traceparent')) || make();
*
* fetch('/downstream', {
*   headers: { traceparent: traceparent.child() }
* })
* ```
*
* @module
*/
/**
* The Traceparent type represents a W3C Trace Context traceparent header.
*/
export interface Traceparent {
	version: string;
	trace_id: string;
	parent_id: string;
	flags: number;
	/**
	* Branches the traceparent into a new child, creating a new {@link parent_id}.
	* Note; All existing flags are copied over.
	*/
	child(): Traceparent;
	toString(): string;
}
/** The bitmask represenging a sampled traceparent */
export declare const FLAG_SAMPLE = 0b00000001;
/** The bitmask representing a random traceparent */
export declare const FLAG_RANDOM = 0b00000010;
/**
* Makes a new Traceparent which one can then `toString()` to get the value.
*
* By default the flags are both {@link FLAG_SAMPLE|sampled} and {@link FLAG_RANDOM|randomed}.
*
* @example
*
* ```js
* const id = make();
* String(id); // 00-aa3ee2e08eb134a292fb799969f2de62-62994ea4677bc463-01
* const child = id.child();
* String(child); // 00-aa3ee2e08eb134a292fb799969f2de62-5402ac6f6874d505-01
* ```
*/
export declare function make(): Traceparent;
/**
* Allows you to parse an incoming value into the areas, easy for a server to continue the trace chain.
*
* @example
* ```js
* const parent = parse(req.headers.traceparent); // 00-aa3ee2e08eb134a292fb799969f2de62-62994ea4677bc463-00
* const child = parent.child();
* String(child); // 00-aa3ee2e08eb134a292fb799969f2de62-5402ac6f6874d505-01
* ```
*/
export declare function parse(value: string): Traceparent | null;
/**
* Modifies the flags of a Traceparent to sample the traceparent flag bit.
*
* > [!NOTE]
* > You may wish to `.child()` before you sample, as is required by the {@link https://www.w3.org/TR/trace-context-2/#sampled-flag|spec}
*/
export declare function sample(id: Traceparent): void;
/**
* Modifies the flags of a Traceparent to unsample the traceparent flag bit.
*
* > [!NOTE]
* > You may wish to `.child()` before you unsample, as is required by the {@link https://www.w3.org/TR/trace-context-2/#sampled-flag|spec}
*/
export declare function unsample(id: Traceparent): void;
/** Returns if the traceparent is currently being sampled. */
export declare function is_sampled(id: Traceparent): boolean;
/** Returns if the traceparent is currently random. */
export declare function is_randomed(id: Traceparent): boolean;
declare let;