Skip to content

Commit

Permalink
chore: lint markdown
Browse files Browse the repository at this point in the history
  • Loading branch information
blumamir committed Apr 27, 2024
1 parent 182405f commit e602c3b
Showing 1 changed file with 3 additions and 1 deletion.
4 changes: 3 additions & 1 deletion GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,14 +172,15 @@ The diag channel can be used to troubleshoot issues with instrumentation package
### Patching Messages

When OpenTelemetry is installed in a user application, and expected spans are missing from generated traces, it is often useful to differentiate between the following scenarios:

- The instrumentation is not auto loaded - due to issue with the require/import interception, an unsupported version of the instrumented package, or some other issue. This knowledge can pin-point the issue to the instrumentation package.
- The instrumentation patch was applied but expected spans are missing - this can spot the light on the instrumented package logic, configuration, limits, otel sdk, or other issues.

It can also be useful to know when the instrumentation is loaded and patched, to understand the order of operations in the application.

Instrumentation packages should use the `@opentelemetry/instrumentation` package `BaseInstrumentation` class to register patches and unpatch callbacks for specific require/import of the instrumented package, it's dependency or an internal module file. When this mechanism is used, the base class will automatically emit a debug message on instrumentation diag component logger, looking like this:
```
```shell
@opentelemetry/instrumentation-foo Applying instrumentation patch for module on require hook {
module: 'foo',
version: '1.2.3',
Expand All @@ -190,6 +191,7 @@ Instrumentation packages should use the `@opentelemetry/instrumentation` package
Instrumentation should not add additional debug messages for triggering the patching and unpatching callbacks, as the base class will handle this.
Instrumentation may add additional patch/unpatch messages for specific functions if it is expected to help in troubleshooting issues with the instrumentation. Few examples:
- If the patch logic is conditional, and user can benefit from ensuring the condition is met and the patch happened. `koa` patching logic examine an object and branch between patching it as router vs middleware, which is applied at runtime. `awslambda` will aboard patching if the environment is not configured properly.
- When the patch is not applied directly on a `moduleExports` object in the `BaseInstrumentation` callbacks, but rather from an event in the package, like creating new client instance, registering a listener, etc. `fastify` instrumentation applies a patch when an hook is added to the fastify app instance, which is patched from `moduleExports`.
- In situations where the patch logic is not trivial and it helps to specify patch events in the right context and nuances. `aws-lambda` logs additional properties extracted from the labmda framework and exposes them for troubleshooting.
Expand Down

0 comments on commit e602c3b

Please sign in to comment.