@mertdogar/otel-cf-workers 1.0.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Erwin van der Koogh
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,308 @@
+# otel-cf-workers
+
+An OpenTelemetry compatible library for instrumenting and exporting traces from Cloudflare Workers.
+
+## Getting started
+
+```bash
+npm install @mertdogar/otel-cf-workers @opentelemetry/api
+```
+
+> [!IMPORTANT]
+> To be able to use the Open Telemetry library you have to add the NodeJS compatibility flag in your `wrangler.toml` file.
+
+```json
+compatibility_flags = [ "nodejs_compat" ]
+```
+
+> [!IMPORTANT]
+> As of version 1.0.0-rc.52, we are no longer providing a CommonJS build. It is already hard enough trying to write a library that deals with all of Cloudflare's functionality over every single combination of compatibility flags and dates. Combining that with two different build is just too much. If you really need CommonJS support, please create a ticket (if there isn't already) and describe your use-case.
+
+For a simple setup example with configuration examples, have a look at the [Quickstart Example](https://github.com/evanderkoogh/otel-cf-workers/tree/main/examples/worker)
+
+### Code example
+
+```typescript
+import { trace } from '@opentelemetry/api'
+import { instrument, ResolveConfigFn } from '@mertdogar/otel-cf-workers'
+
+export interface Env {
+	HONEYCOMB_API_KEY: string
+	OTEL_TEST: KVNamespace
+}
+
+const handler = {
+	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+		await fetch('https://cloudflare.com')
+
+		const greeting = "G'day World"
+		trace.getActiveSpan()?.setAttribute('greeting', greeting)
+		ctx.waitUntil(fetch('https://workers.dev'))
+		return new Response(`${greeting}!`)
+	},
+}
+
+const config: ResolveConfigFn = (env: Env, _trigger) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'greetings' },
+	}
+}
+
+export default instrument(handler, config)
+```
+
+## Auto-instrumentation
+
+### Workers
+
+Wrapping your exporter handler with the `instrument` function is all you need to do to automatically have not just the functions of you handler auto-instrumented, but also the global `fetch` and `caches` and all of the supported bindings in your environment such as KV.
+
+See the quick start code sample for an example of how it works.
+
+### Durable Objects
+
+Instrumenting Durable Objects work very similar to the regular Worker auto-instrumentation. Instead of wrapping the handler in an `instrument` call, you wrap the Durable Object class with the `instrumentDO` function.
+
+```typescript
+import { instrumentDO, PartialTraceConfig } from '@mertdogar/otel-cf-workers'
+
+const config: ResolveConfigFn = (env: Env, _trigger) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'greetings-do' },
+	}
+}
+
+class OtelDO implements DurableObject {
+	async fetch(request: Request): Promise<Response> {
+		return new Response('Hello World!')
+	}
+}
+
+const TestOtelDO = instrumentDO(OtelDO, doConfig)
+
+export { TestOtelDO }
+```
+
+## Creating custom spans
+
+While auto-instrumenting should take care of a lot of the information that you would want to add, there will always be application specific information you want to send along.
+
+You can get the current active span by doing:
+
+```typescript
+import {trace} from '@opentelemetry/api'
+
+const handler = {
+	async fetch(request: Request) {
+		const span = trace.getActiveSpan()
+		if(span) span.setAttributes('name', 'value')
+		....
+	}
+}
+```
+
+Or if you want to create a new span:
+
+```typescript
+import { trace } from '@opentelemetry/api'
+
+const handler = {
+	async fetch(request: Request) {
+		const tracer = trace.getTracer('my_own_tracer_name')
+		return tracer.startActiveSpan('name', (span) => {
+			const response = await doSomethingAwesome
+			span.end()
+			return response
+		})
+	},
+}
+```
+
+## Configuration
+
+For configuration you can either pass in a [TraceConfig](https://github.com/evanderkoogh/otel-cf-workers/blob/0da125a4e16ff13e49f8e486340eb6080e631eb9/src/types.ts#L24C18-L24C29) or a function that takes the Environment and the trigger for this particular trace and returns a `TraceConfig`.
+
+Because the configuration function is run separately for every new invocation, it is possible to tailor your configuration for every type of request. So it is for example possible to have a much lower sampling ratio for your healthchecks than actual API requests.
+
+### Exporter
+
+In the `exporter`, you need to configure where to send spans to. It can take either an instance of a class that implements the standard Open Telemetry `SpanExporter`interface, or an object with the properties `url` and optionally `headers` to configure an exporter for the Open Telemetry format.
+
+Examples:
+
+```typescript
+const exporter = new ConsoleSpanExporter()
+```
+
+```typescript
+const exporter = {
+	url: 'https://api.honeycomb.io/v1/traces',
+	headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+}
+```
+
+### Fetch
+
+`includeTraceContext` is used to specify if outgoing requests should include the TraceContext so that the other service can participate in a distributed trace.
+The default is `true` for all outgoing requests, but you can turn it off for all requests with `false`, or specify a method that takes the outgoing `Request` method and return a boolean on whether to include the tracing context.
+
+Example:
+
+```typescript
+const fetchConf = (request: Request): boolean => {
+	return new URL(request.url).hostname === 'example.com'
+}
+```
+
+### Handlers
+
+The `handlers` field of the configuration overrides the way in which event handlers, such as `fetch` or `queue`, are instrumented.
+
+#### Fetch Handler
+
+`acceptTraceContext` is used to specify if incoming requests handled by `fetch` should accept a TraceContext and participate in a distributed trace.
+The default is `true` for all incoming requests, but you can turn it off for all requests with `false` or specify a method that takes the incoming `Request` and returns a boolean indicating whether to accept the tracing context.
+
+Example:
+
+```typescript
+const fetchConf = (request: Request): boolean => {
+	return new URL(request.url).hostname === 'example.com'
+}
+```
+
+### PostProcessor
+
+The PostProcessor function is called just before exporting the spans and allows you to make any changes to the spans before sending this. For example to remove entire spans, or to remove or redact security or privacy sensitive data.
+
+Example:
+
+```typescript
+const postProcessor = (spans: ReadableSpan[]): ReadableSpan[] => {
+	spans[0].attributes['http.url'] = 'REDACTED'
+	return spans
+}
+```
+
+### Sampling
+
+One of the challenges of tracing is that for sites and applications with a lot of traffic it becomes prohibitively expensive to store every trace. So the question becomes how to store the ones with the most interesting information and drop the ones that are the least interesting. That is where sampling comes in.
+
+#### Head Sampling vs Tail Sampling
+
+There are two (complimentary) sampling strategies: Head Sampling and Tail Sampling and in a lot of cases you will want to use a combination to get the most information into the least amount of sampled events.
+
+To understand the difference in head vs tail sampling in our context, we have to understand distributed tracing. A distributed trace is one that spans multiple systems or services. At every point another service is called, we inject a header with the information about the trace, such as the traceId, the parentSpanId and a hint if this trace is sampled.
+
+Head Sampling, as the name implies, is done at the beginning of a span/trace. In our case it is mostly used to signal to downstream systems whether or not to sample a particular trace, because we can always drop the current services portion of a trace during Tail Sampling.
+
+Head Sampling can be configured with any standard Open Telemetry `Sampler` or an object with a `ratio` property and optional `acceptRemote` property. The default is the AlwaysOnSampler, which samples every single request.
+
+Examples:
+
+```typescript
+const headSampler = new AlwaysOnSampler()
+```
+
+```typescript
+const headSampler = {
+	acceptRemote: false //Whether to accept incoming trace contexts
+	ratio: 0.5 //number between 0 and 1 that represents the ratio of requests to sample. 0 is none and 1 is all requests.
+}
+```
+
+Tail Sampling on the other hand is done at the end. Because we record every single span, even if it isn't head sampled, it is possible to still sample the local part of a trace in say the event of an error.
+
+Example:
+
+```typescript
+const tailSampler = (traceInfo: LocalTrace): boolean => {
+	const localRootSpan = traceInfo.localRootSpan as unknown as ReadableSpan
+	return (localRootSpan.spanContext().traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED
+}
+```
+
+The default is a tailSampler that samples traces that have been head sampled or if the local root span is marked as an error.
+
+#### Service
+
+Service identifies the service and version to help with querying.
+
+Example:
+
+```typescript
+const service = {
+	name: 'some_name' //required. The name of your service
+	version: '1.0.4' //optional: An opaque version string. Can be a semver or git hash for example
+	namespace: 'namespace' //optional: Useful to group multiple services together in one namespace.
+}
+```
+
+### Propagation
+
+Register a custom propagator with:
+
+```ts
+const config: ResolveConfigFn = (env: Env, _trigger) => {
+	return {
+		propagator: new MyCoolPropagator(),
+	}
+}
+```
+
+## Distributed Tracing
+
+One of the advantages of using Open Telemetry is that it makes it easier to do distributed tracing through multiple different services. This library will automatically inject the W3C Trace Context headers when making calls to Durable Objects or outbound fetch calls.
+
+## Limitations
+
+- The worker runtime does not expose accurate timing information to protect against side-channel attacks such as Spectre and will only update the clock on IO, so any CPU heavy processing will look like it takes 0 milliseconds.
+- Not everything is auto-instrumented yet. See the lists below for what is and isn't.
+
+Triggers:
+
+- [x] Email (`handler.email`)
+- [x] HTTP (`handler.fetch`)
+- [x] Queue (`handler.queue`)
+- [x] Cron (`handler.scheduled`)
+- [ ] Tail (`handler.tail`)
+- [x] Durable Objects fetch
+- [x] Durable Objects alarm
+- [ ] Durable Objects hibernated WebSocket
+- [x] waitUntil (`ctx.waitUntil`)
+
+Globals/built-ins:
+
+- [x] Fetch
+- [x] Caches
+- [x] Durable Object Storage
+
+Cloudflare modules
+
+- [ ] `cloudflare:email`
+- [ ] `cloudflare:sockets`
+
+Bindings:
+
+- [x] KV
+- [x] Queue
+- [x] Durable Objects
+- [ ] R2
+- [x] D1
+- [x] Service Bindings
+- [x] Analytics Engine
+- [ ] Browser Rendering
+- [ ] Workers AI
+- [ ] Email Sending
+- [ ] mTLS
+- [ ] Vectorize
+- [ ] Hyperdrive
+- [ ] Workers for Platforms Dispatch

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import { SpanExporter, ReadableSpan, Sampler, SpanProcessor, TimedEvent } from '@opentelemetry/sdk-trace-base';
+import { TextMapPropagator, SpanOptions, Context, Attributes, Span, SpanContext, SpanKind, SpanStatus, HrTime, Link, TimeInput, AttributeValue, Exception } from '@opentelemetry/api';
+import { ExportResult, InstrumentationScope } from '@opentelemetry/core';
+import { OTLPExporterError } from '@opentelemetry/otlp-exporter-base';
+import { DurableObject as DurableObject$1 } from 'cloudflare:workers';
+import { Resource } from '@opentelemetry/resources';
+
+interface OTLPExporterConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+declare class OTLPExporter implements SpanExporter {
+    private headers;
+    private url;
+    constructor(config: OTLPExporterConfig);
+    export(items: any[], resultCallback: (result: ExportResult) => void): void;
+    private _export;
+    send(items: any[], onSuccess: () => void, onError: (error: OTLPExporterError) => void): void;
+    shutdown(): Promise<void>;
+}
+
+type IncludeTraceContextFn = (request: Request) => boolean;
+interface FetcherConfig {
+    includeTraceContext?: boolean | IncludeTraceContextFn;
+}
+type AcceptTraceContextFn = (request: Request) => boolean;
+interface FetchHandlerConfig {
+    /**
+     * Whether to enable context propagation for incoming requests to `fetch`.
+     * This enables or disables distributed tracing from W3C Trace Context headers.
+     * @default true
+     */
+    acceptTraceContext?: boolean | AcceptTraceContextFn;
+}
+
+type OrPromise<T extends any> = T | Promise<T>;
+type ResolveConfigFn<Env = any> = (env: Env, trigger: Trigger) => TraceConfig;
+type ConfigurationOption = TraceConfig | ResolveConfigFn;
+type PostProcessorFn = (spans: ReadableSpan[]) => ReadableSpan[];
+type ExporterConfig = OTLPExporterConfig | SpanExporter;
+interface InitialSpanInfo {
+    name: string;
+    options: SpanOptions;
+    context?: Context;
+}
+interface HandlerInstrumentation<T extends Trigger, R extends any> {
+    getInitialSpanInfo: (trigger: T) => InitialSpanInfo;
+    getAttributesFromResult?: (result: Awaited<R>) => Attributes;
+    instrumentTrigger?: (trigger: T) => T;
+    executionSucces?: (span: Span, trigger: T, result: Awaited<R>) => void;
+    executionFailed?: (span: Span, trigger: T, error?: any) => void;
+}
+type TraceFlushableSpanProcessor = SpanProcessor & {
+    forceFlush: (traceId?: string) => Promise<void>;
+};
+interface HandlerConfig {
+    fetch?: FetchHandlerConfig;
+}
+interface ServiceConfig {
+    name: string;
+    namespace?: string;
+    version?: string;
+}
+interface ParentRatioSamplingConfig {
+    acceptRemote?: boolean;
+    ratio: number;
+}
+type HeadSamplerConf = Sampler | ParentRatioSamplingConfig;
+interface SamplingConfig<HS extends HeadSamplerConf = HeadSamplerConf> {
+    headSampler?: HS;
+    tailSampler?: TailSampleFn;
+}
+interface InstrumentationOptions {
+    instrumentGlobalFetch?: boolean;
+    instrumentGlobalCache?: boolean;
+}
+interface TraceConfigBase {
+    service: ServiceConfig;
+    handlers?: HandlerConfig;
+    fetch?: FetcherConfig;
+    postProcessor?: PostProcessorFn;
+    sampling?: SamplingConfig;
+    propagator?: TextMapPropagator;
+    instrumentation?: InstrumentationOptions;
+}
+interface TraceConfigExporter extends TraceConfigBase {
+    exporter: ExporterConfig;
+}
+interface TraceConfigSpanProcessors extends TraceConfigBase {
+    spanProcessors: SpanProcessor | SpanProcessor[];
+}
+type TraceConfig = TraceConfigExporter | TraceConfigSpanProcessors;
+declare function isSpanProcessorConfig(config: TraceConfig): config is TraceConfigSpanProcessors;
+interface ResolvedTraceConfig extends TraceConfigBase {
+    handlers: Required<HandlerConfig>;
+    fetch: Required<FetcherConfig>;
+    postProcessor: PostProcessorFn;
+    sampling: Required<SamplingConfig<Sampler>>;
+    spanProcessors: SpanProcessor[];
+    propagator: TextMapPropagator;
+    instrumentation: InstrumentationOptions;
+}
+interface DOConstructorTrigger {
+    id: string;
+    name?: string;
+}
+type Trigger = Request | MessageBatch | ScheduledController | DOConstructorTrigger | 'do-alarm' | ForwardableEmailMessage;
+
+interface LocalTrace {
+    readonly traceId: string;
+    readonly localRootSpan: ReadableSpan;
+    readonly spans: ReadableSpan[];
+}
+type TailSampleFn = (traceInfo: LocalTrace) => boolean;
+declare function multiTailSampler(samplers: TailSampleFn[]): TailSampleFn;
+declare const isHeadSampled: TailSampleFn;
+declare const isRootErrorSpan: TailSampleFn;
+declare function createSampler(conf: ParentRatioSamplingConfig): Sampler;
+
+type DO = DurableObject | DurableObject$1;
+type DOClass = {
+    new (state: DurableObjectState, env: any): DO;
+};
+
+declare class PromiseTracker {
+    _outstandingPromises: Promise<unknown>[];
+    get outstandingPromiseCount(): number;
+    track(promise: Promise<unknown>): void;
+    wait(): Promise<void>;
+}
+
+type Env = Record<string, any>;
+declare function isRequest(trigger: Trigger): trigger is Request;
+declare function isMessageBatch(trigger: Trigger): trigger is MessageBatch;
+declare function isAlarm(trigger: Trigger): trigger is 'do-alarm';
+declare function exportSpans(traceId: string, tracker?: PromiseTracker): Promise<void>;
+declare function instrument<E extends Env, Q, C>(handler: ExportedHandler<E, Q, C>, config: ConfigurationOption): ExportedHandler<E, Q, C>;
+declare function instrumentDO(doClass: DOClass, config: ConfigurationOption): DOClass;
+declare const __unwrappedFetch: typeof fetch;
+
+type OnSpanEnd = (span: Span) => void;
+interface SpanInit {
+    attributes: unknown;
+    name: string;
+    onEnd: OnSpanEnd;
+    resource: Resource;
+    spanContext: SpanContext;
+    parentSpanContext?: SpanContext;
+    links?: Link[];
+    parentSpanId?: string;
+    spanKind?: SpanKind;
+    startTime?: TimeInput;
+}
+declare class SpanImpl implements Span, ReadableSpan {
+    name: string;
+    private readonly _spanContext;
+    private readonly onEnd;
+    readonly parentSpanId?: string;
+    readonly parentSpanContext?: SpanContext | undefined;
+    readonly kind: SpanKind;
+    readonly attributes: Attributes;
+    status: SpanStatus;
+    endTime: HrTime;
+    private _duration;
+    readonly startTime: HrTime;
+    readonly events: TimedEvent[];
+    readonly links: Link[];
+    readonly resource: Resource;
+    instrumentationScope: InstrumentationScope;
+    private _ended;
+    private _droppedAttributesCount;
+    private _droppedEventsCount;
+    private _droppedLinksCount;
+    constructor(init: SpanInit);
+    addLink(link: Link): this;
+    addLinks(links: Link[]): this;
+    spanContext(): SpanContext;
+    setAttribute(key: string, value?: AttributeValue): this;
+    setAttributes(attributes: Attributes): this;
+    addEvent(name: string, attributesOrStartTime?: Attributes | TimeInput, startTime?: TimeInput): this;
+    setStatus(status: SpanStatus): this;
+    updateName(name: string): this;
+    end(endTime?: TimeInput): void;
+    isRecording(): boolean;
+    recordException(exception: Exception, time?: TimeInput): void;
+    get duration(): HrTime;
+    get ended(): boolean;
+    get droppedAttributesCount(): number;
+    get droppedEventsCount(): number;
+    get droppedLinksCount(): number;
+}
+
+declare class MultiSpanExporter implements SpanExporter {
+    private exporters;
+    constructor(exporters: Array<SpanExporter>);
+    export(items: any[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}
+declare class MultiSpanExporterAsync implements SpanExporter {
+    private exporters;
+    constructor(exporters: Array<SpanExporter>);
+    export(items: any[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}
+
+declare class TraceState {
+    private unexportedSpans;
+    private inprogressSpans;
+    private exporter;
+    private exportPromises;
+    private localRootSpan?;
+    private traceDecision?;
+    constructor(exporter: SpanExporter);
+    addSpan(span: Span): void;
+    endSpan(span: ReadableSpan): void;
+    sample(): void;
+    flush(): Promise<void>;
+    private isSpanInProgress;
+    private exportSpans;
+}
+type traceId = string;
+declare class BatchTraceSpanProcessor implements TraceFlushableSpanProcessor {
+    private exporter;
+    private traces;
+    constructor(exporter: SpanExporter);
+    getTraceState(traceId: string): TraceState;
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(traceId?: traceId): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+declare function withNextSpan(attrs: Attributes): void;
+
+export { BatchTraceSpanProcessor, type ConfigurationOption, type DOConstructorTrigger, type ExporterConfig, type HandlerConfig, type HandlerInstrumentation, type InitialSpanInfo, type InstrumentationOptions, type LocalTrace, MultiSpanExporter, MultiSpanExporterAsync, OTLPExporter, type OTLPExporterConfig, type OrPromise, type ParentRatioSamplingConfig, type PostProcessorFn, type ResolveConfigFn, type ResolvedTraceConfig, type SamplingConfig, type ServiceConfig, SpanImpl, type TailSampleFn, type TraceConfig, type TraceFlushableSpanProcessor, type Trigger, __unwrappedFetch, createSampler, exportSpans, instrument, instrumentDO, isAlarm, isHeadSampled, isMessageBatch, isRequest, isRootErrorSpan, isSpanProcessorConfig, multiTailSampler, withNextSpan };