From 891d299a2bffe8aa02e22806cbd8c904cd531ddd Mon Sep 17 00:00:00 2001 From: Anton Vasin Date: Tue, 11 Aug 2020 17:05:15 +0300 Subject: [PATCH] TypeScript definitions --- lib/types.d.ts | 180 ++++++++++++++++++++++++++++++++++++++++++++++ package-lock.json | 13 ++-- package.json | 2 + 3 files changed, 188 insertions(+), 7 deletions(-) create mode 100644 lib/types.d.ts diff --git a/lib/types.d.ts b/lib/types.d.ts new file mode 100644 index 00000000..d9450495 --- /dev/null +++ b/lib/types.d.ts @@ -0,0 +1,180 @@ +import { IncomingMessage } from "http"; + +export interface SamplerResponse { + sampleRate: number; + shouldSample: boolean; +} + +export interface BeelineOpts { + writeKey?: string; + dataset?: string; + serviceName?: string; + sampleRate?: number; + enabledInstrumentations?: string[]; + + samplerHook?(event: unknown): SamplerResponse; + presendHook?(event: unknown): void; + disableInstrumentation?: boolean; + + express?: { + userContext?: MetadataContext; + traceIdSource?: string | ((req: IncomingMessage) => string); + parentIdSource?: string | ((req: IncomingMessage) => string); + }; + + fastify?: { + userContext?: MetadataContext; + traceIdSource?: string | ((req: IncomingMessage) => string); + parentIdSource?: string | ((req: IncomingMessage) => string); + }; + + mongodb?: { + includeDocuments?: boolean; + }; + + httpTraceParserHook?: HttpTraceParserHook; + httpTracePropagationHook?: HttpTracePropagationHook; +} + +export interface Schema { + "meta.type"?: string; + "meta.node_version"?: string; + "meta.beeline_version"?: string; + "meta.package"?: string; + "meta.package_version"?: string; + "meta.instrumentations"?: string; + "meta.instrumentation_count"?: string; + "meta.local_hostname"?: string; + duration_ms?: number; + "trace.trace_id"?: string; + "trace.trace_id_source"?: string; + "trace.parent_id"?: string; + "trace.span_id"?: string; + service_name?: string; + name?: string; +} + +export interface Span { + addContext(metadataContext: MetadataContext): void; + payload: Schema & MetadataContext; + startTime: number; + startTimeHR: [number, number]; +} + +export type MetadataContext = Record; + +export interface TraceContext { + traceId?: string; + parentSpanId?: string; + dataset?: string; + customContext?: MetadataContext; + source?: string; +} + +export interface ExecutionContext { + id?: string; + traceContext?: MetadataContext; + stack?: Span[]; + dataset?: string; +} + +export type MarshallableContext = MetadataContext | ExecutionContext; + +export interface Timer { + name: string; + startTimeHR: [number, number]; +} + +type SpanFn = (...args: any[]) => F; + +type Configure = (opts?: BeelineOpts) => Beeline & Configure; + +type Headers = Record; +export type HttpTraceParserHook = (req: IncomingMessage) => TraceContext; +export type HttpTracePropagationHook = (ctx: TraceContext) => Headers; + +export interface Beeline { + traceActive(): boolean; + clearTrace(): void; + getTraceContext(): ExecutionContext; + + startTrace( + metadataContext?: MetadataContext, + traceId?: string, + parentSpanId?: string, + dataset?: string, + propagatedContext?: MetadataContext + ): Span | undefined; + finishTrace(trace: Span): void; + withTrace( + metadataContext: MetadataContext, + fn: SpanFn, + traceId?: string, + parentSpanId?: string, + dataset?: string + ): F; + + startSpan(metadataContext?: MetadataContext): Span | undefined; + finishSpan(event: Span, rollup?: string): void; + withSpan(metadataContext: MetadataContext, fn: SpanFn, rollup?: string): F; + startAsyncSpan(metadataContext: MetadataContext, fn: SpanFn): F; + + startTimer(name: string): Timer; + finishTimer(timer: Timer): void; + withTimer(name: string, fn: SpanFn): F; + + addTraceContext(metadataContext: MetadataContext): void; + addContext(metadataContext: MetadataContext): void; + /** @deprecated this method will be removed in the next major release. */ + removeContext(key: string): void; + + customContext: { + /** @deprecated this method will be removed in the next major release. Please use .addTraceContext. */ + add(k: string, v: any): void; + /** @deprecated this method will be removed in the next major release. */ + remove(k: string): void; + }; + + bindFunctionToTrace(fn: SpanFn): F; + runWithoutTrace(fn: SpanFn): F; + + flush(): Promise; + + getInstrumentations(): string[]; + + /** @deprecated this method will be removed in the next major release. Please use honeycomb.marshalTraceContext() instead. */ + marshalTraceContext(ctx: MarshallableContext): string; + /** @deprecated this method will be removed in the next major release. Please use honeycomb.unmarshalTraceContext() instead. */ + unmarshalTraceContext(ctx: string): TraceContext | undefined; + + honeycomb: { + marshalTraceContext(ctx: MarshallableContext): string; + unmarshalTraceContext(honeycombTraceHeader: string): TraceContext | undefined; + httpTraceParserHook: HttpTraceParserHook; + httpTracePropagationHook: HttpTracePropagationHook; + TRACE_HTTP_HEADER: string; + }; + + w3c: { + marshalTraceContext(ctx: MarshallableContext): string; + unmarshalTraceContext(traceparent: string, tracestate?: string): TraceContext | undefined; + httpTraceParserHook: HttpTraceParserHook; + httpTracePropagationHook: HttpTracePropagationHook; + TRACE_HTTP_HEADER: string; + }; + + aws: { + marshalTraceContext(ctx: MarshallableContext): string; + unmarshalTraceContext(amazonTraceHeader: string): TraceContext | undefined; + httpTraceParserHook: HttpTraceParserHook; + httpTracePropagationHook: HttpTracePropagationHook; + TRACE_HTTP_HEADER: string; + }; + + /** @deprecated this constant will be removed in the next major release. Please use honeycomb.TRACE_HTTP_HEADER instead. */ + TRACE_HTTP_HEADER: string; +} + +declare const beeline: Beeline & Configure; + +export default beeline; diff --git a/package-lock.json b/package-lock.json index 88bc6917..da318d9c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1182,10 +1182,9 @@ } }, "@types/node": { - "version": "14.14.20", - "resolved": "https://registry.npmjs.org/@types/node/-/node-14.14.20.tgz", - "integrity": "sha512-Y93R97Ouif9JEOWPIUyU+eyIdyRqQR0I8Ez1dzku4hDx34NWh4HbtIc3WNzwB1Y9ULvNGeu5B8h8bVL5cAk4/A==", - "dev": true + "version": "14.14.25", + "resolved": "https://registry.npmjs.org/@types/node/-/node-14.14.25.tgz", + "integrity": "sha512-EPpXLOVqDvisVxtlbvzfyqSsFeQxltFbluZNRndIb8tr9KiBnYNLzrc1N3pyKUCww2RNrfHDViqDWWE1LCJQtQ==" }, "@types/normalize-package-data": { "version": "2.4.0", @@ -1200,9 +1199,9 @@ "dev": true }, "@types/prettier": { - "version": "2.1.6", - "resolved": "https://registry.npmjs.org/@types/prettier/-/prettier-2.1.6.tgz", - "integrity": "sha512-6gOkRe7OIioWAXfnO/2lFiv+SJichKVSys1mSsgyrYHSEjk8Ctv4tSR/Odvnu+HWlH2C8j53dahU03XmQdd5fA==", + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@types/prettier/-/prettier-2.2.0.tgz", + "integrity": "sha512-O3SQC6+6AySHwrspYn2UvC6tjo6jCTMMmylxZUFhE1CulVu5l3AxU6ca9lrJDTQDVllF62LIxVSx5fuYL6LiZg==", "dev": true }, "@types/stack-utils": { diff --git a/package.json b/package.json index 38a255bb..49923b55 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "url": "https://github.com/honeycombio/beeline-nodejs/issues" }, "main": "lib/index.js", + "types": "lib/types.d.ts", "scripts": { "test": "jest", "debug-test": "DEBUG=honeycomb-beeline:* jest", @@ -64,6 +65,7 @@ }, "dependencies": { "@opentelemetry/core": "^0.16.0", + "@types/node": "^14.14.25", "array-flatten": "^3.0.0", "debug": "^4.2.0", "libhoney": "^2.2.1",