diff --git a/apps/docs/src/config.ts b/apps/docs/src/config.ts index 443cd4e9..880bf53d 100644 --- a/apps/docs/src/config.ts +++ b/apps/docs/src/config.ts @@ -53,7 +53,7 @@ const nestRpc = (name: string): string => `en/nestjs/rpc/${name}`; const nestOverview = (type: Transport): string => `en/nestjs/${type}/overview`; export type Sidebar = Record< - typeof KNOWN_LANGUAGE_CODES[number], + (typeof KNOWN_LANGUAGE_CODES)[number], Record >; export const SIDEBAR: Sidebar = { @@ -167,5 +167,11 @@ export const SIDEBAR: Sidebar = { link: 'en/cli', }, ], + '@ogma/instrumentation': [ + { + text: 'Overview', + link: 'en/instrumentation', + }, + ], }, }; diff --git a/apps/docs/src/pages/en/instrumentation.md b/apps/docs/src/pages/en/instrumentation.md new file mode 100644 index 00000000..c7c08f2b --- /dev/null +++ b/apps/docs/src/pages/en/instrumentation.md @@ -0,0 +1,70 @@ +--- +id: instrumentation +title: Instrumentation +layout: ../../layouts/MainLayout.astro +--- + +This module provides automatic instrumentation for injection of trace context for the [`ogma`](https://www.npmjs.com/package/@ogma/logger) module, which may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package and is included in the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle. + +If total installation size is not constrained, it is recommended to use the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle with [@opentelemetry/sdk-node](`https://www.npmjs.com/package/@opentelemetry/sdk-node`) for the most seamless instrumentation experience. + +Compatible with OpenTelemetry JS API and SDK `1.0+`. + +## Installation + +```bash +npm install --save @ogma/instrumentation +``` + +## Usage + +```js +const { + NodeTracerProvider +} = require('@opentelemetry/sdk-trace-node'); +const { + registerInstrumentations +} = require('@opentelemetry/instrumentation'); +const { OgmaInstrumentation } = require('@ogma/instrumentation'); + +const provider = new NodeTracerProvider(); +provider.register(); + +registerInstrumentations({ + instrumentations: [ + new OgmaInstrumentation({ + // Optional hook to insert additional context to log object. + logHook: (span, record, level) => { + record['resource.service.name'] = + provider.resource.attributes['service.name']; + } + }) + // other instrumentations + ] +}); + +const { Ogma } = require('@ogma/logger'); +const logger = new Ogma(); +logger.info('foobar'); +// {"level":"INFO","meta":{"trace_id":"80d20824ae2f4a039c9ddd6463ecf2a2","span_id":"bdf2a9482f641cb9","trace_flags":"01"},"message":"foobar"...} +``` + +### Fields added to ogma log objects + +For the current active span, the following fields are injected: + +- `trace_id` +- `span_id` +- `trace_flags` + +When no span context is active or the span context is invalid, injection is skipped. + +### Supported versions + +`>=3.2.0` + +## Useful links + +- For more information on OpenTelemetry, visit: +- For more about OpenTelemetry JavaScript: +- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] diff --git a/packages/instrumentation/README.md b/packages/instrumentation/README.md index dcc03b4b..2a079c25 100644 --- a/packages/instrumentation/README.md +++ b/packages/instrumentation/README.md @@ -1,7 +1,66 @@ -# instrumentation +# Ogma Instrumentation for OpenTelemetry -This library was generated with [Nx](https://nx.dev). +This module provides automatic instrumentation for injection of trace context for the [`ogma`](https://www.npmjs.com/package/@ogma/logger) module, which may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package and is included in the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle. -## Building +If total installation size is not constrained, it is recommended to use the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle with [@opentelemetry/sdk-node](`https://www.npmjs.com/package/@opentelemetry/sdk-node`) for the most seamless instrumentation experience. -Run `nx build instrumentation` to build the library. +Compatible with OpenTelemetry JS API and SDK `1.0+`. + +## Installation + +```bash +npm install --save @ogma/instrumentation +``` + +## Usage + +```js +const { + NodeTracerProvider +} = require('@opentelemetry/sdk-trace-node'); +const { + registerInstrumentations +} = require('@opentelemetry/instrumentation'); +const { OgmaInstrumentation } = require('@ogma/instrumentation'); + +const provider = new NodeTracerProvider(); +provider.register(); + +registerInstrumentations({ + instrumentations: [ + new OgmaInstrumentation({ + // Optional hook to insert additional context to log object. + logHook: (span, record, level) => { + record['resource.service.name'] = + provider.resource.attributes['service.name']; + } + }) + // other instrumentations + ] +}); + +const { Ogma } = require('@ogma/logger'); +const logger = new Ogma(); +logger.info('foobar'); +// {"level":"INFO","meta":{"trace_id":"80d20824ae2f4a039c9ddd6463ecf2a2","span_id":"bdf2a9482f641cb9","trace_flags":"01"},"message":"foobar"...} +``` + +### Fields added to ogma log objects + +For the current active span, the following fields are injected: + +- `trace_id` +- `span_id` +- `trace_flags` + +When no span context is active or the span context is invalid, injection is skipped. + +### Supported versions + +`>=3.2.0` + +## Useful links + +- For more information on OpenTelemetry, visit: +- For more about OpenTelemetry JavaScript: +- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] diff --git a/packages/instrumentation/package.json b/packages/instrumentation/package.json index a498c0a1..1fdc2366 100644 --- a/packages/instrumentation/package.json +++ b/packages/instrumentation/package.json @@ -14,6 +14,5 @@ }, "type": "commonjs", "main": "./src/index.js", - "typings": "./src/index.d.ts", - "private": true + "typings": "./src/index.d.ts" }