You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: GUIDELINES.md
+33Lines changed: 33 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -164,3 +164,36 @@ To support this use case, you can choose one of the following options:
164
164
};
165
165
...
166
166
```
167
+
168
+
## Diag Logging
169
+
170
+
The OpenTelemetry diagnostic logging channel can be used to troubleshoot issues with instrumentation packages.
171
+
172
+
### Patching Messages
173
+
174
+
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:
175
+
176
+
- 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.
177
+
- The instrumentation patch was applied but expected spans are missing --this can suggest an issue with instrumented package logic, configuration, limits, otel sdk, or other issues.
178
+
179
+
It can also be useful to know when the instrumentation is loaded and patched, to understand the order of operations in the application.
180
+
181
+
Instrumentation packages should use the `@opentelemetry/instrumentation`package`InstrumentationBase`classto 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:
182
+
183
+
```shell
184
+
@opentelemetry/instrumentation-foo Applying instrumentation patch for module on require hook {
185
+
module: 'foo',
186
+
version: '1.2.3',
187
+
baseDir: '<your directory>/node_modules/foo'
188
+
}
189
+
```
190
+
191
+
Instrumentation should not add additional debug messages for triggering the patching and unpatching callbacks, as the base class will handle this.
192
+
193
+
Instrumentation may add additional patch/unpatch messages for specific functions if it is expected to help in troubleshooting issues with the instrumentation. Few examples:
194
+
195
+
- 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. `aws-lambda` will abort patching if the environment is not configured properly.
196
+
- When the patch is not applied directly on a `moduleExports` object in the `InstrumentationBase` callbacks, but rather from an event in the package, like creating new client instance, registering a listener, etc. `fastify` instrumentation applies a patch when a hook is added to the fastify app instance, which is patched from `moduleExports`.
197
+
- 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 lambda framework and exposes them for troubleshooting.
198
+
199
+
The cases above are not covered by the base class and offer additional context to the user troubleshooting an issue with the instrumentation.
0 commit comments