basant307/AI_Governance_Project

1# OpenTelemetry Tracing SDK2 3[![NPM Published Version][npm-img]][npm-url]4[![Apache License][license-image]][license-image]5 6The `tracing` module contains the foundation for all tracing SDKs of [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js).7 8Used standalone, this module provides methods for manual instrumentation of code, offering full control over span creation for client-side JavaScript (browser) and Node.js.9 10It does **not** provide automated instrumentation of known libraries, context propagation or distributed-context out-of-the-box.11 12For a `TracerProvider` that includes default context management and propagation for Node.js, please see13[@opentelemetry/sdk-trace-node](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node).14 15For a `TracerProvider` that includes default context management and propagation for Browser, please see16[@opentelemetry/sdk-trace-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-web).17 18## Installation19 20```bash21npm install --save @opentelemetry/api22npm install --save @opentelemetry/sdk-trace-base23```24 25## Usage26 27```js28const { trace } = require('@opentelemetry/api');29const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');30 31// To start a trace, you first need to initialize the Tracer provider.32// NOTE: The default OpenTelemetry tracer provider does not record any tracing information.33//       Registering a working tracer provider allows the API methods to record traces.34trace.setGlobalTracerProvider(new BasicTracerProvider());35 36// Important: requires a context manager and propagator to be registered manually.37// propagation.setGlobalPropagator(propagator);     // replace `propagator` with your `TextMapPropagator`, for example: `W3CTraceContextPropagator` from `@openetelemetry/core`38// context.setGlobalContextManager(contextManager); // replace `contextManager` with your `ContextManager`: `AsyncLocalStorageContextManager` from `@openetelemetry/async-hooks`39 40// To create a span in a trace, we used the global singleton tracer to start a new span.41const span = trace.getTracer('default').startSpan('foo');42 43// Set a span attribute44span.setAttribute('key', 'value');45 46// We must end the spans so they become available for exporting.47span.end();48```49 50## Config51 52Tracing configuration is a merge of user supplied configuration with both the default53configuration as specified in [config.ts](./src/config.ts) and an54environmentally configurable sampling (via `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`).55 56## Built-in Samplers57 58Sampler is used to make decisions on `Span` sampling.59 60### AlwaysOn Sampler61 62Samples every trace regardless of upstream sampling decisions.63 64> This is used as a default Sampler65 66```js67const {68  AlwaysOnSampler,69  BasicTracerProvider,70} = require("@opentelemetry/sdk-trace-base");71 72const tracerProvider = new BasicTracerProvider({73  sampler: new AlwaysOnSampler()74});75```76 77### AlwaysOff Sampler78 79Doesn't sample any trace, regardless of upstream sampling decisions.80 81```js82const {83  AlwaysOffSampler,84  BasicTracerProvider,85} = require("@opentelemetry/sdk-trace-base");86 87const tracerProvider = new BasicTracerProvider({88  sampler: new AlwaysOffSampler()89});90```91 92### TraceIdRatioBased Sampler93 94Samples some percentage of traces, calculated deterministically using the trace ID.95Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.96 97The `TraceIDRatioSampler` may be used with the `ParentBasedSampler` to respect the sampled flag of an incoming trace.98 99```js100const {101  BasicTracerProvider,102  TraceIdRatioBasedSampler,103} = require("@opentelemetry/sdk-trace-base");104 105const tracerProvider = new BasicTracerProvider({106  // See details of ParentBasedSampler below107  sampler: new ParentBasedSampler({108    // Trace ID Ratio Sampler accepts a positional argument109    // which represents the percentage of traces which should110    // be sampled.111    root: new TraceIdRatioBasedSampler(0.5)112  });113});114```115 116### ParentBased Sampler117 118- This is a composite sampler. `ParentBased` helps distinguished between the119following cases:120  - No parent (root span).121  - Remote parent with `sampled` flag `true`122  - Remote parent with `sampled` flag `false`123  - Local parent with `sampled` flag `true`124  - Local parent with `sampled` flag `false`125 126Required parameters:127 128- `root(Sampler)` - Sampler called for spans with no parent (root spans)129 130Optional parameters:131 132- `remoteParentSampled(Sampler)` (default: `AlwaysOn`)133- `remoteParentNotSampled(Sampler)` (default: `AlwaysOff`)134- `localParentSampled(Sampler)` (default: `AlwaysOn`)135- `localParentNotSampled(Sampler)` (default: `AlwaysOff`)136 137|Parent| parent.isRemote() | parent.isSampled()| Invoke sampler|138|--|--|--|--|139|absent| n/a | n/a |`root()`|140|present|true|true|`remoteParentSampled()`|141|present|true|false|`remoteParentNotSampled()`|142|present|false|true|`localParentSampled()`|143|present|false|false|`localParentNotSampled()`|144 145```js146const {147  AlwaysOffSampler,148  BasicTracerProvider,149  ParentBasedSampler,150  TraceIdRatioBasedSampler,151} = require("@opentelemetry/sdk-trace-base");152 153const tracerProvider = new BasicTracerProvider({154  sampler: new ParentBasedSampler({155    // By default, the ParentBasedSampler will respect the parent span's sampling156    // decision. This is configurable by providing a different sampler to use157    // based on the situation. See configuration details above.158    //159    // This will delegate the sampling decision of all root traces (no parent)160    // to the TraceIdRatioBasedSampler.161    // See details of TraceIdRatioBasedSampler above.162    root: new TraceIdRatioBasedSampler(0.5)163  })164});165```166 167## Example168 169See [examples/basic-tracer-node](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/basic-tracer-node) for an end-to-end example, including exporting created spans.170 171## Useful links172 173- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>174- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>175- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]176 177## License178 179Apache 2.0 - See [LICENSE][license-url] for more information.180 181[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions182[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE183[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat184[npm-url]: https://www.npmjs.com/package/@opentelemetry/sdk-trace-base185[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fsdk-trace-base.svg186