diff --git a/content/en/docs/concepts/instrumentation-scope/_index.md b/content/en/docs/concepts/instrumentation-scope/_index.md new file mode 100644 index 00000000000..1f1cd390ca6 --- /dev/null +++ b/content/en/docs/concepts/instrumentation-scope/_index.md @@ -0,0 +1,41 @@ +--- +title: Instrumentation Scope +weight: 80 +--- + +The [Instrumentation Scope](/docs/specs/otel/glossary/#instrumentation-scope) +represents a logical unit within the application code with which the emitted +telemetry can be associated. + +It is typically the developer’s choice to decide what denotes a reasonable +instrumentation scope, e.g. a module, a package or a class can be chosen as +instrumentation scope. In the case of a library or framework, it is a common +approach to use an identifier as scope that is unique to the library or +framework, such as a fully qualified name and version of the library or +framework. If the library itself does not have built-in OpenTelemetry +instrumentation, and an Instrumentation Library is used instead, it is +recommended to use the name and version of the Instrumentation Library as the +instrumentation scope. + +The Instrumentation Scope is defined by a name and version pair when a Tracer, +Meter or Logger instance is obtained from a provider. Each span, metric or log +record created by the instance will be associated with the provided +Instrumentation Scope. + +In your observability backend, this allows you to slice and dice your telemetry +data by the Instrumentation Scope, e.g. to see which of your users are using +which version of a library and what the performance of that library version is +or to pin point a problem to a specific module of your application. + +The diagram below illustrates a trace with multiple instrumentation scopes. The +different scopes are represented by different colors: + +- At the top the `/api/placeOrder` span is generated by the used HTTP framework +- The spans in green (`CheckoutService::placeOrder`, `prepareOrderItems` and + `checkout`) are application code, grouped by the `CheckoutService` class. +- The spans for `CartService::getCart` and `ProductService::getProduct` are also + application code, grouped by the `CartService` and `ProductService` classes. +- The spans in orange (`Cache::find`) and light blue (`DB::query`) are library + code, grouped by the library name and version. + +![This image illustrates a trace with multiple instrumentation scopes](spans-with-instrumentation-scope.svg) diff --git a/content/en/docs/concepts/instrumentation-scope/spans-with-instrumentation-scope.svg b/content/en/docs/concepts/instrumentation-scope/spans-with-instrumentation-scope.svg new file mode 100644 index 00000000000..ccbfc25c43d --- /dev/null +++ b/content/en/docs/concepts/instrumentation-scope/spans-with-instrumentation-scope.svg @@ -0,0 +1,3 @@ + + + /api/placeOrderCheckoutService::placeOrderprepareOrderItemsCartService::getCartCache::findCache::findProductService::getProductCache::findCache::findDB::querycheckoutCache::findDB::query \ No newline at end of file diff --git a/content/en/docs/instrumentation/java/manual.md b/content/en/docs/instrumentation/java/manual.md index 91e1c89e88b..a4ed7ab0a04 100644 --- a/content/en/docs/instrumentation/java/manual.md +++ b/content/en/docs/instrumentation/java/manual.md @@ -570,9 +570,9 @@ Tracer tracer = openTelemetry.getTracer("instrumentation-scope-name", "instrumen The values of `instrumentation-scope-name` and `instrumentation-scope-version` should uniquely identify the -[instrumentation scope](/docs/specs/otel/glossary/#instrumentation-scope), such -as the package, module or class name. This will help later help determining what -the source of telemetry is. While the name is required, the version is still +[Instrumentation Scope](/docs/concepts/instrumentation-scope/), such as the +package, module or class name. This will help later help determining what the +source of telemetry is. While the name is required, the version is still recommended despite being optional. Note, that all `Tracer`s that are created by a single `OpenTelemetry` instance will interoperate, regardless of name. @@ -582,7 +582,7 @@ avoid trickier application load issues when other required dependencies are involved. In the case of the [example app](#example-app), there are two places where a -tracer may be acquired with an appropriate instrumentation scope: +tracer may be acquired with an appropriate Instrumentation Scope: First, in the `index` method of the `RollController` as follows: diff --git a/content/en/docs/instrumentation/js/manual.md b/content/en/docs/instrumentation/js/manual.md index 5c84568526d..ef69280ca66 100644 --- a/content/en/docs/instrumentation/js/manual.md +++ b/content/en/docs/instrumentation/js/manual.md @@ -466,9 +466,9 @@ const tracer = opentelemetry.trace.getTracer( The values of `instrumentation-scope-name` and `instrumentation-scope-version` should uniquely identify the -[instrumentation scope](/docs/specs/otel/glossary/#instrumentation-scope), such -as the package, module or class name. While the name is required, the version is -still recommended despite being optional. +[Instrumentation Scope](/docs/concepts/instrumentation-scope/), such as the +package, module or class name. While the name is required, the version is still +recommended despite being optional. It's generally recommended to call `getTracer` in your app when you need it rather than exporting the `tracer` instance to the rest of your app. This helps @@ -476,7 +476,7 @@ avoid trickier application load issues when other required dependencies are involved. In the case of the [example app](#example-app), there are two places where a -tracer may be acquired with an appropriate instrumentation scope: +tracer may be acquired with an appropriate Instrumentation Scope: First, in the _application file_ `app.ts` (or `app.js`):