@vercel/otel 1.3.0 → 1.3.1-58ed7f91-20240221184234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,58 @@
1
+ # @vercel/otel
2
+
3
+ ## 1.3.1-58ed7f91-20240221184234
4
+
5
+ ### Patch Changes
6
+
7
+ - 58ed7f9: Include API docs
8
+
9
+ ## 1.3.0
10
+
11
+ ### Minor Changes
12
+
13
+ - 79110fc: resource.name and resourceNameTemplate for fetch instrumentation
14
+ - 965fce6: DataDog resource/operation mapping
15
+
16
+ ### Patch Changes
17
+
18
+ - 67b5337: Edge performance.timeOrigin is set as 0
19
+ - bc65efe: Automatically propagate context to localhost on dev, and same branch_host on preview/prod
20
+ - bc65efe: Added vercel.branch_host resource attribute
21
+
22
+ ## 1.2.1
23
+
24
+ ### Patch Changes
25
+
26
+ - 79fbec0: Eliminate race condition between response end and trace end
27
+ - 31ce66b: More docs on fetch instrumentation
28
+
29
+ ## 1.2.0
30
+
31
+ ### Minor Changes
32
+
33
+ - 7a04c92: Avoid OTLP longbits to avoid compatibility problems with some OTLP collectors
34
+
35
+ ## 1.1.0
36
+
37
+ ### Minor Changes
38
+
39
+ - 83ad945: Ensure that fetch receives the original input
40
+
41
+ ## 1.0.1
42
+
43
+ ### Patch Changes
44
+
45
+ - a9d3a36: Remove "experimental" warning
46
+
47
+ ## 1.0.0
48
+
49
+ ### Major Changes
50
+
51
+ - 2daf631: - Support for Node and Edge environments
52
+ - Telemetry context propagation, including [W3C Trace Context](https://www.w3.org/TR/trace-context/)
53
+ - Fetch API instrumentation with context propagation.
54
+ - Support and auto-configuration for [Vercel OTEL collector](https://vercel.com/docs/observability/otel-overview/quickstart).
55
+ - Enhanced metadata reporting.
56
+ - Sampling support.
57
+ - Custom tracing exporter support.
58
+ - Batched trace exporting.
package/README.md CHANGED
@@ -14,12 +14,21 @@ npm install @vercel/otel
14
14
 
15
15
  ## 📚 Usage
16
16
 
17
+ To configure OpenTelemetry SDK, call the `registerOTel` in the `instumentation.ts`:
18
+
17
19
  ```javascript
18
20
  import { registerOTel } from "@vercel/otel";
19
- import { trace } from "@opentelemetry/api";
20
21
 
21
- // Register the OpenTelemetry.
22
- registerOTel("your-service-name");
22
+ export function register() {
23
+ // Register the OpenTelemetry.
24
+ registerOTel("your-service-name");
25
+ }
26
+ ```
27
+
28
+ To create custom spans in your code, use the OpenTelemetry API:
29
+
30
+ ```javascript
31
+ import { trace } from "@opentelemetry/api";
23
32
 
24
33
  // Now you can use the OpenTelemetry APIs
25
34
  const span = trace.getTracer("your-component").startSpan("your-operation");
@@ -50,7 +59,11 @@ Registers the OpenTelemetry SDK with the specified configuration. Configuration
50
59
  - `traceSampler`: The sampler to be used to decide which requests should be traced. By default, all requests are traced. This option can be changed to, for instance, only trace 1% of all requests.
51
60
  - `spanProcessors` and `traceExporter`: The export mechanism for traces. By default, `@vercel/otel` configures the best export mechanism for the environment. For instance, if a [tracing integrations](https://vercel.com/docs/observability/otel-overview/quickstart) is configured on Vercel, this integration will be automatically used for export; otherwise an [OTLP exporter](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#otlp-exporter) can be used if configured in environment variables.
52
61
 
53
- See API for more details.
62
+ See [API](./dist/docs/index.html) for more details.
63
+
64
+ ## 📝 Changelog
65
+
66
+ See [CHANGELOG.md](./CHANGELOG.md).
54
67
 
55
68
  ## 🔗 References
56
69
 
@@ -2,6 +2,9 @@ import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
2
2
  import type { OTLPExporterConfigBase } from "@opentelemetry/otlp-exporter-base";
3
3
  import type { IExportTraceServiceRequest } from "@opentelemetry/otlp-transformer";
4
4
  import { OTLPExporterEdgeBase } from "./otlp-exporter-base";
5
+ /**
6
+ * OTLP exporter for the `http/json` protocol. Compatible with the "edge" runtime.
7
+ */
5
8
  export declare class OTLPHttpJsonTraceExporter extends OTLPExporterEdgeBase<ReadableSpan, IExportTraceServiceRequest> {
6
9
  convert(spans: ReadableSpan[]): IExportTraceServiceRequest;
7
10
  toMessage(serviceRequest: IExportTraceServiceRequest): {
@@ -2,6 +2,9 @@ import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
2
2
  import type { OTLPExporterConfigBase } from "@opentelemetry/otlp-exporter-base";
3
3
  import type { IExportTraceServiceRequest } from "@opentelemetry/otlp-transformer";
4
4
  import { OTLPExporterEdgeBase } from "./otlp-exporter-base";
5
+ /**
6
+ * OTLP exporter for the `http/protobuf` protocol. Compatible with the "edge" runtime.
7
+ */
5
8
  export declare class OTLPHttpProtoTraceExporter extends OTLPExporterEdgeBase<ReadableSpan, IExportTraceServiceRequest> {
6
9
  convert(spans: ReadableSpan[]): IExportTraceServiceRequest;
7
10
  toMessage(serviceRequest: IExportTraceServiceRequest): {
@@ -3,4 +3,20 @@ export type * from "./types";
3
3
  export { OTLPHttpJsonTraceExporter } from "./exporters/exporter-trace-otlp-http-fetch";
4
4
  export { OTLPHttpProtoTraceExporter } from "./exporters/exporter-trace-otlp-proto-fetch";
5
5
  export { type FetchInstrumentationConfig, FetchInstrumentation, } from "./instrumentations/fetch";
6
+ /**
7
+ * Registers the OpenTelemetry SDK with the specified service name and the default configuration.
8
+ * Should be included in the `instrumentation.ts`. For example:
9
+ * ```ts
10
+ * import { registerOTel } from "@vercel/otel";
11
+ *
12
+ * export function register() {
13
+ * registerOTel({
14
+ * serviceName: "my-app",
15
+ * ...
16
+ * });
17
+ * }
18
+ * ```
19
+ *
20
+ * @param optionsOrServiceName - Either a service name as a string or a configuration object.
21
+ */
6
22
  export declare function registerOTel(optionsOrServiceName?: Configuration | string): void;
@@ -1,9 +1,33 @@
1
1
  import type { TracerProvider } from "@opentelemetry/api";
2
2
  import type { Instrumentation, InstrumentationConfig } from "@opentelemetry/instrumentation";
3
+ /**
4
+ * Configuration for the "fetch" instrumentation.
5
+ */
3
6
  export interface FetchInstrumentationConfig extends InstrumentationConfig {
7
+ /**
8
+ * A set of URL matchers (string prefix or regex) that should be ignored from tracing.
9
+ * By default all URLs are traced. Example: `fetch: { ignoreUrls: [/example.com/] }`.
10
+ */
4
11
  ignoreUrls?: (string | RegExp)[];
12
+ /**
13
+ * A set of URL matchers (string prefix or regex) for which the tracing context
14
+ * should be propagated (see [`propagators`](Configuration#propagators)).
15
+ * By default the context is propagated _only_ for the
16
+ * [deployment URLs](https://vercel.com/docs/deployments/generated-urls), all
17
+ * other URLs should be enabled explicitly.
18
+ * Example: `fetch: { propagateContextUrls: [ /my.api/ ] }`.
19
+ */
5
20
  propagateContextUrls?: (string | RegExp)[];
21
+ /**
22
+ * A set of URL matchers (string prefix or regex) for which the tracing context
23
+ * should not be propagated (see [`propagators`](Configuration#propagators)). This allows you to exclude a
24
+ * subset of URLs allowed by the [`propagateContextUrls`](FetchInstrumentationConfig#propagateContextUrls).
25
+ */
6
26
  dontPropagateContextUrls?: (string | RegExp)[];
27
+ /**
28
+ * A string for the "resource.name" attribute that can include attribute expressions in `{}`.
29
+ * Example: `fetch: { resourceNameTemplate: "{http.host}" }`.
30
+ */
7
31
  resourceNameTemplate?: string;
8
32
  }
9
33
  export declare class FetchInstrumentation implements Instrumentation {
@@ -13,18 +13,77 @@ export type InstrumentationOptionOrName = InstrumentationOption | "fetch" | "aut
13
13
  export interface InstrumentationConfiguration {
14
14
  fetch?: FetchInstrumentationConfig;
15
15
  }
16
+ /**
17
+ * OpenTelemetry SDK configuration.
18
+ */
16
19
  export interface Configuration {
20
+ /**
21
+ * The name of your service, used as the app name in many OpenTelemetry backends.
22
+ * Can be overriden by the `OTEL_SERVICE_NAME` environment variable.
23
+ */
17
24
  serviceName?: string;
25
+ /**
26
+ * The resource attributes.
27
+ * By default, `@vercel/otel` configures relevant Vercel attributes based on the
28
+ * [environment](https://vercel.com/docs/projects/environment-variables/system-environment-variables),
29
+ * including:
30
+ * - `service.name` - the service name.
31
+ * - `node.env` - the value of `NODE_ENV` environment variable.
32
+ * - `vercel.env` - the Vercel deployment environment such as "production" or "preview" (`VERCEL_ENV` environment variable).
33
+ * - `vercel.region` - the Vercel deployment region (`VERCEL_REGION` environment variable).
34
+ * - `vercel.runtime` - "nodejs" or "edge" (`NEXT_RUNTIME` environment variable).
35
+ * - `vercel.sha` - the Vercel deployment Git SHA (`VERCEL_GIT_COMMIT_SHA` environment variable).
36
+ * - `vercel.host` - the Vercel deployment host for the Git SHA (`VERCEL_URL` environment variable).
37
+ * - `vercel.branch_host` - the Vercel deployment host for the branch (`VERCEL_BRANCH_URL` environment variable).
38
+ */
18
39
  attributes?: ResourceAttributes;
19
40
  resourceDetectors?: DetectorSync[];
20
41
  autoDetectResources?: boolean;
42
+ /**
43
+ * A set of instrumentations.
44
+ * By default, `@vercel/otel` configures ["fetch"](FetchInstrumentationConfig) instrumentation.
45
+ */
21
46
  instrumentations?: InstrumentationOptionOrName[];
47
+ /**
48
+ * Customize configuration for predefined instrumentations:
49
+ * - [fetch](FetchInstrumentationConfig)
50
+ */
22
51
  instrumentationConfig?: InstrumentationConfiguration;
23
52
  contextManager?: ContextManager;
24
53
  idGenerator?: IdGenerator;
54
+ /**
55
+ * A set of propagators that may extend inbound and outbound contexts.
56
+ * Use the "auto" value to include all default propagators.
57
+ * By default, `@vercel/otel` configures [W3C Trace Context](https://www.w3.org/TR/trace-context/) propagator.
58
+ * This option can be also configured via the [`OTEL_PROPAGATORS`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) environment variable.
59
+ * Example: `{ propagators: ["auto", new MyPropagator()] }`
60
+ */
25
61
  propagators?: PropagatorOrName[];
62
+ /**
63
+ * The sampler to be used to decide which requests should be traced.
64
+ * Use the "auto" value to use the default sampler.
65
+ * By default, all requests are traced. This option can be changed to,
66
+ * for instance, only trace 1% of all requests.
67
+ * This option can also be configured via the [`OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) environment variable.
68
+ */
26
69
  traceSampler?: SampleOrName;
70
+ /**
71
+ * A set of span processors to be used to process captured spans.
72
+ * Use the "auto" value to include all default span processors.
73
+ * By default, `@vercel/otel` auto-configures an export processor based on the environment.
74
+ * See [traceExporter](Configuration#traceExporter) for more details.
75
+ */
27
76
  spanProcessors?: SpanProcessorOrName[];
77
+ /**
78
+ * A custom exporter for traces.
79
+ * Use the "auto" value to include the best export mechanism for the environment.
80
+ * By default, `@vercel/otel` configures the best export mechanism for the
81
+ * environment. For instance, if a [tracing integrations](https://vercel.com/docs/observability/otel-overview/quickstart) is
82
+ * configured on Vercel, this integration will be automatically used for export; otherwise an
83
+ * [OTLP exporter](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#otlp-exporter)
84
+ * can be used if configured via environment variables, such as `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`
85
+ * and `OTEL_EXPORTER_OTLP_HEADERS`.
86
+ */
28
87
  traceExporter?: SpanExporterOrName;
29
88
  spanLimits?: SpanLimits;
30
89
  logRecordProcessor?: LogRecordProcessor;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vercel/otel",
3
- "version": "1.3.0",
3
+ "version": "1.3.1-58ed7f91-20240221184234",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -42,7 +42,9 @@
42
42
  },
43
43
  "types": "./dist/types/index.d.ts",
44
44
  "files": [
45
- "dist"
45
+ "dist",
46
+ "LICENSE",
47
+ "CHANGELOG.md"
46
48
  ],
47
49
  "engines": {
48
50
  "node": ">=18"
@@ -69,6 +71,7 @@
69
71
  "esbuild": "^0.19.4",
70
72
  "rimraf": "3.0.2",
71
73
  "tsx": "^4.6.2",
74
+ "typedoc": "^0.25.8",
72
75
  "typescript": "^5",
73
76
  "vitest": "0.33.0",
74
77
  "eslint-config": "1.0.0",