feat: add client-side trace sampling

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!

[Giran Moodley (giranm)]

Summary

Adds deterministic client-side head sampling for native Braintrust JavaScript traces. Sampling decisions are trace-id based, so independently created children and distributed continuations stay coherent.

Usage

import{initLogger}from"braintrust";constlogger=initLogger({projectName: "production",sampleRate: 0.2,// Record approximately 20% of new project-root traces.});// Override the logger default for an exceptional new root trace.constpriority=logger.startSpan({name: "priority-request",sampleRate: 1,});

Expected behavior

• sampleRate accepts a finite fraction from 0 through 1 and defaults to 1; invalid values throw.
• The decision for a new native project root is deterministic from its trace ID. Its native children inherit that decision, and span.isRecording() exposes it.
• A sampled-out trace preserves context, stable IDs, and traceparent propagation with trace flags 00, but queues no Braintrust rows or instrumentation payload work.
• An existing local, exported, W3C, or OpenTelemetry parent takes precedence over either configured rate. New local Experiment roots remain recorded, except when continuing an unsampled parent.
• When OpenTelemetry owns creation, its provider sampler is authoritative. The @braintrust/otel bridge preserves that result without applying Logger.sampleRate a second time.

Implementation

• Add Logger.sampleRate, root-span overrides, and Span.isRecording().
• Preserve trace flags in native export tokens, native context, W3C propagation, and OpenTelemetry context.
• Skip trace extraction and export work for sampled-out instrumentation spans while retaining lifecycle and context behavior.
• Add documentation, changesets, unit coverage, and the trace-sampling E2E scenario.

Validation

• Focused native tests: 282 passed; final logger, propagation, and sampling set: 248 passed.
• Trace-sampling E2E scenario passed repeatedly.
• Isolated OpenTelemetry v1 and v2 fixture suites: 123 passed each.
• Type checks, build, API compatibility, formatting, lint, and diff checks passed.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If this PR is still relevant, please leave a comment, push an update, or remove the stale label. Thank you for your contributions!