diff --git a/GUIDELINES.md b/GUIDELINES.md index e32c007de7..f6df8e0056 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -172,6 +172,7 @@ 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. @@ -179,7 +180,7 @@ It can also be useful to know when the instrumentation is loaded and patched, to 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', @@ -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.