From 8a85f1c7fddab12eb00b64db41f0c49c8776c0d6 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:17:11 +0300 Subject: [PATCH 01/20] chore(mongoose): remove diag prints in patch --- plugins/node/instrumentation-mongoose/src/mongoose.ts | 5 ----- 1 file changed, 5 deletions(-) diff --git a/plugins/node/instrumentation-mongoose/src/mongoose.ts b/plugins/node/instrumentation-mongoose/src/mongoose.ts index 3de0ea33ee..47884597aa 100644 --- a/plugins/node/instrumentation-mongoose/src/mongoose.ts +++ b/plugins/node/instrumentation-mongoose/src/mongoose.ts @@ -141,7 +141,6 @@ export class MongooseInstrumentation extends InstrumentationBase { private patchAggregateExec(moduleVersion: string | undefined) { const self = this; - this._diag.debug('patched mongoose Aggregate exec function'); return (originalAggregate: Function) => { return function exec(this: any, callback?: Function) { if ( @@ -183,7 +182,6 @@ export class MongooseInstrumentation extends InstrumentationBase { private patchQueryExec(moduleVersion: string | undefined) { const self = this; - this._diag.debug('patched mongoose Query exec function'); return (originalExec: Function) => { return function exec(this: any, callback?: Function) { if ( @@ -226,7 +224,6 @@ export class MongooseInstrumentation extends InstrumentationBase { private patchOnModelMethods(op: string, moduleVersion: string | undefined) { const self = this; - this._diag.debug(`patching mongoose Model '${op}' operation`); return (originalOnModelFunction: Function) => { return function method(this: any, options?: any, callback?: Function) { if ( @@ -275,7 +272,6 @@ export class MongooseInstrumentation extends InstrumentationBase { // the aggregate of Model, and set the context on the Aggregate object private patchModelAggregate() { const self = this; - this._diag.debug('patched mongoose model aggregate function'); return (original: Function) => { return function captureSpanContext(this: any) { const currentSpan = trace.getSpan(context.active()); @@ -290,7 +286,6 @@ export class MongooseInstrumentation extends InstrumentationBase { private patchAndCaptureSpanContext(funcName: string) { const self = this; - this._diag.debug(`patching mongoose query ${funcName} function`); return (original: Function) => { return function captureSpanContext(this: any) { this[_STORED_PARENT_SPAN] = trace.getSpan(context.active()); From 535195420a224409b367856c4671f7f1da8427cf Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:17:30 +0300 Subject: [PATCH 02/20] chore(tedious): remove diag prints in patch --- plugins/node/instrumentation-tedious/src/instrumentation.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/plugins/node/instrumentation-tedious/src/instrumentation.ts b/plugins/node/instrumentation-tedious/src/instrumentation.ts index d9c23eeb86..df4021c982 100644 --- a/plugins/node/instrumentation-tedious/src/instrumentation.ts +++ b/plugins/node/instrumentation-tedious/src/instrumentation.ts @@ -123,9 +123,6 @@ export class TediousInstrumentation extends InstrumentationBase { private _patchQuery(operation: string) { return (originalMethod: UnknownFunction): UnknownFunction => { const thisPlugin = this; - this._diag.debug( - `TediousInstrumentation: patched Connection.prototype.${operation}` - ); function patchedMethod(this: ApproxConnection, request: ApproxRequest) { if (!(request instanceof EventEmitter)) { From eba86f2604429acf17eb9cfbb27241a1dc301e1b Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:20:54 +0300 Subject: [PATCH 03/20] chore(dns): remove diag prints in patch --- .../opentelemetry-instrumentation-dns/src/instrumentation.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/node/opentelemetry-instrumentation-dns/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-dns/src/instrumentation.ts index 37ad2822fb..9c55f60f29 100644 --- a/plugins/node/opentelemetry-instrumentation-dns/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-dns/src/instrumentation.ts @@ -103,7 +103,6 @@ export class DnsInstrumentation extends InstrumentationBase { private _getPatchLookupFunction( original: (hostname: string, ...args: unknown[]) => void ) { - diag.debug('patch lookup function'); const plugin = this; return function patchedLookup( this: {}, From ab58270f70402faa816fa7601ed96c3c553249e1 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:23:24 +0300 Subject: [PATCH 04/20] chore(fastify): remove diag prints in patch --- .../opentelemetry-instrumentation-fastify/src/instrumentation.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/node/opentelemetry-instrumentation-fastify/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-fastify/src/instrumentation.ts index aebf1bf721..3b9138ec26 100644 --- a/plugins/node/opentelemetry-instrumentation-fastify/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-fastify/src/instrumentation.ts @@ -198,7 +198,6 @@ export class FastifyInstrumentation extends InstrumentationBase { fastify: () => FastifyInstance; }): () => FastifyInstance { const instrumentation = this; - this._diag.debug('Patching fastify constructor function'); function fastify(this: FastifyInstance, ...args: any) { const app: FastifyInstance = moduleExports.fastify.apply(this, args); From 9811baa0c0e48f2c5a049ae6e5d4a1e6c63298c7 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:23:38 +0300 Subject: [PATCH 05/20] chore(hapi): remove diag prints in patch --- .../opentelemetry-instrumentation-hapi/src/instrumentation.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-hapi/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-hapi/src/instrumentation.ts index 4e3d1d4ce9..397c502264 100644 --- a/plugins/node/opentelemetry-instrumentation-hapi/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-hapi/src/instrumentation.ts @@ -137,7 +137,6 @@ export class HapiInstrumentation extends InstrumentationBase { original: RegisterFunction ): RegisterFunction { const instrumentation: HapiInstrumentation = this; - api.diag.debug('Patching Hapi.Server register function'); return function register( this: Hapi.Server, pluginInput: HapiPluginInput, @@ -173,7 +172,6 @@ export class HapiInstrumentation extends InstrumentationBase { pluginName?: string ) { const instrumentation: HapiInstrumentation = this; - api.diag.debug('Patching Hapi.Server ext function'); return function ext( this: ThisParameterType, @@ -235,7 +233,6 @@ export class HapiInstrumentation extends InstrumentationBase { pluginName?: string ) { const instrumentation: HapiInstrumentation = this; - api.diag.debug('Patching Hapi.Server route function'); return function route( this: Hapi.Server, route: HapiServerRouteInput From 53a481112c3bfdc645b9495ed80d49fb45c66dd4 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:25:07 +0300 Subject: [PATCH 06/20] chore(knex): remove diag prints in patch --- .../src/instrumentation.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts index ce45403efc..86507e4656 100644 --- a/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts @@ -109,10 +109,7 @@ export class KnexInstrumentation extends InstrumentationBase { ); return Client; }, - (Client: any, moduleVersion) => { - api.diag.debug( - `Removing ${basePath}/client.js patch for ${constants.MODULE_NAME}@${moduleVersion}` - ); + (Client: any) => { this._unwrap(Client.prototype, 'queryBuilder'); this._unwrap(Client.prototype, 'schemaBuilder'); this._unwrap(Client.prototype, 'raw'); From 203f82d1092d759921c26b41631cfc68abb686f9 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:28:45 +0300 Subject: [PATCH 07/20] chore(mysql): remove diag prints in patch --- .../src/instrumentation.ts | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts index 2e4ba8675e..e2438ac47e 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts @@ -84,7 +84,6 @@ export class MySQLInstrumentation extends InstrumentationBase { 'mysql', ['2.*'], (moduleExports: typeof mysqlTypes) => { - diag.debug('Patching mysql.createConnection'); if (isWrapped(moduleExports.createConnection)) { this._unwrap(moduleExports, 'createConnection'); } @@ -94,7 +93,6 @@ export class MySQLInstrumentation extends InstrumentationBase { this._patchCreateConnection() as any ); - diag.debug('Patching mysql.createPool'); if (isWrapped(moduleExports.createPool)) { this._unwrap(moduleExports, 'createPool'); } @@ -104,7 +102,6 @@ export class MySQLInstrumentation extends InstrumentationBase { this._patchCreatePool() as any ); - diag.debug('Patching mysql.createPoolCluster'); if (isWrapped(moduleExports.createPoolCluster)) { this._unwrap(moduleExports, 'createPoolCluster'); } @@ -130,7 +127,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchCreateConnection() { return (originalCreateConnection: Function) => { const thisPlugin = this; - diag.debug('MySQLInstrumentation#patch: patched mysql createConnection'); return function createConnection( _connectionUri: string | mysqlTypes.ConnectionConfig @@ -153,7 +149,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchCreatePool() { return (originalCreatePool: Function) => { const thisPlugin = this; - diag.debug('MySQLInstrumentation#patch: patched mysql createPool'); return function createPool(_config: string | mysqlTypes.PoolConfig) { const pool = originalCreatePool(...arguments); @@ -173,7 +168,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchPoolEnd(pool: any) { return (originalPoolEnd: Function) => { const thisPlugin = this; - diag.debug('MySQLInstrumentation#patch: patched mysql pool end'); return function end(callback?: unknown) { const nAll = (pool as any)._allConnections.length; const nFree = (pool as any)._freeConnections.length; @@ -196,7 +190,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchCreatePoolCluster() { return (originalCreatePoolCluster: Function) => { const thisPlugin = this; - diag.debug('MySQLInstrumentation#patch: patched mysql createPoolCluster'); return function createPool(_config: string | mysqlTypes.PoolConfig) { const cluster = originalCreatePoolCluster(...arguments); @@ -215,7 +208,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchAdd(cluster: mysqlTypes.PoolCluster) { return (originalAdd: Function) => { const thisPlugin = this; - diag.debug('MySQLInstrumentation#patch: patched mysql pool cluster add'); return function add(id: string, config: unknown) { // Unwrap if unpatch has been called if (!thisPlugin['_enabled']) { @@ -241,9 +233,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchGetConnection(pool: mysqlTypes.Pool | mysqlTypes.PoolCluster) { return (originalGetConnection: Function) => { const thisPlugin = this; - diag.debug( - 'MySQLInstrumentation#patch: patched mysql pool getConnection' - ); return function getConnection( arg1?: unknown, @@ -308,7 +297,6 @@ export class MySQLInstrumentation extends InstrumentationBase { private _patchQuery(connection: mysqlTypes.Connection | mysqlTypes.Pool) { return (originalQuery: Function): mysqlTypes.QueryFunction => { const thisPlugin = this; - diag.debug('MySQLInstrumentation: patched mysql query'); return function query( query: string | mysqlTypes.Query | mysqlTypes.QueryOptions, From 2b105ccc8bb58be6c1a0d5b759ea4ccba3f4183f Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:29:30 +0300 Subject: [PATCH 08/20] chore(pg): remove diag prints in patch --- .../src/instrumentation.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts index e693488de0..d82c858df0 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts @@ -56,7 +56,6 @@ export class MySQL2Instrumentation extends InstrumentationBase { (moduleExports: any) => { const ConnectionPrototype: mysqlTypes.Connection = moduleExports.Connection.prototype; - api.diag.debug('Patching Connection.prototype.query'); if (isWrapped(ConnectionPrototype.query)) { this._unwrap(ConnectionPrototype, 'query'); } @@ -91,8 +90,6 @@ export class MySQL2Instrumentation extends InstrumentationBase { private _patchQuery(format: formatType, isPrepared: boolean) { return (originalQuery: Function): Function => { const thisPlugin = this; - api.diag.debug('MySQL2Instrumentation: patched mysql query/execute'); - return function query( this: mysqlTypes.Connection, query: string | mysqlTypes.Query | mysqlTypes.QueryOptions, From d3e00f2ff3941dfc010a88d388bb6187cb9c9409 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 08:30:35 +0300 Subject: [PATCH 09/20] chore(redis): remove diag prints in patch --- .../opentelemetry-instrumentation-redis/src/instrumentation.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts index 09ee03e6ad..7a88cd3ce8 100644 --- a/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts @@ -49,7 +49,6 @@ export class RedisInstrumentation extends InstrumentationBase { 'redis', ['^2.6.0', '^3.0.0'], moduleExports => { - diag.debug('Patching redis.RedisClient.internal_send_command'); if ( isWrapped( moduleExports.RedisClient.prototype['internal_send_command'] @@ -66,7 +65,6 @@ export class RedisInstrumentation extends InstrumentationBase { this._getPatchInternalSendCommand() ); - diag.debug('patching redis.RedisClient.create_stream'); if (isWrapped(moduleExports.RedisClient.prototype['create_stream'])) { this._unwrap(moduleExports.RedisClient.prototype, 'create_stream'); } @@ -76,7 +74,6 @@ export class RedisInstrumentation extends InstrumentationBase { this._getPatchCreateStream() ); - diag.debug('patching redis.createClient'); if (isWrapped(moduleExports.createClient)) { this._unwrap(moduleExports, 'createClient'); } From 182405f8380c9eb7704f820b15a3585f1b8d75ed Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 09:36:19 +0300 Subject: [PATCH 10/20] docs: document when to use diag for patch --- GUIDELINES.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/GUIDELINES.md b/GUIDELINES.md index b67f294370..e32c007de7 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -164,3 +164,34 @@ To support this use case, you can choose one of the following options: }; ... ``` + +## Diag Channel + +The diag channel can be used to troubleshoot issues with instrumentation packages. + +### 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: + +``` +@opentelemetry/instrumentation-foo Applying instrumentation patch for module on require hook { + module: 'foo', + version: '1.2.3', + baseDir: '/node_modules/mongoose' +} +``` + +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. + +The cases above are not covered by the base class and offer additional context to the user trouble shooting an issue with the instrumentation. From e602c3bf4ad569ab17be526c0aa77f2069f164a4 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 09:47:49 +0300 Subject: [PATCH 11/20] chore: lint markdown --- GUIDELINES.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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. From 5cf1a4396daaed0bcfea5229eee0ec74d05bd13b Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 09:54:04 +0300 Subject: [PATCH 12/20] fix: unused import --- .../opentelemetry-instrumentation-mysql/src/instrumentation.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts index e2438ac47e..b91ac3469b 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts @@ -17,7 +17,6 @@ import { context, Context, - diag, trace, Span, SpanKind, From c547835b25760106fe3cc0871291f5089222374f Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Sat, 27 Apr 2024 10:27:32 +0300 Subject: [PATCH 13/20] chore: remove unused import --- .../opentelemetry-instrumentation-redis/src/instrumentation.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts index 7a88cd3ce8..b3ccd414b7 100644 --- a/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-redis/src/instrumentation.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { diag } from '@opentelemetry/api'; import { isWrapped, InstrumentationBase, From 124d1aaac690723bfd980683eb3ed2e31632fb16 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Tue, 30 Apr 2024 05:09:44 +0300 Subject: [PATCH 14/20] Update GUIDELINES.md Co-authored-by: Jamie Danielson --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index f6df8e0056..8bf2a0154e 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -184,7 +184,7 @@ Instrumentation packages should use the `@opentelemetry/instrumentation` package @opentelemetry/instrumentation-foo Applying instrumentation patch for module on require hook { module: 'foo', version: '1.2.3', - baseDir: '/node_modules/mongoose' + baseDir: '/node_modules/foo' } ``` From 00e341690ac1fb7fa707577eb732862c1d6322ad Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Tue, 30 Apr 2024 05:09:52 +0300 Subject: [PATCH 15/20] Update GUIDELINES.md Co-authored-by: Jamie Danielson --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index 8bf2a0154e..448dd422c9 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -192,7 +192,7 @@ Instrumentation should not add additional debug messages for triggering the patc 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. +- 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. - 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. From ee1e0facccedae35bb94b19f5ad9bb427785fb9f Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Tue, 30 Apr 2024 05:10:15 +0300 Subject: [PATCH 16/20] Update GUIDELINES.md Co-authored-by: Jamie Danielson --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index 448dd422c9..5d868da893 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -193,7 +193,7 @@ Instrumentation should not add additional debug messages for triggering the patc 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. `aws-lambda` will abort 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`. +- 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 a 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. The cases above are not covered by the base class and offer additional context to the user trouble shooting an issue with the instrumentation. From 4d5050ccadb446223727d59823af7515df0ff46c Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Tue, 30 Apr 2024 05:10:20 +0300 Subject: [PATCH 17/20] Update GUIDELINES.md Co-authored-by: Jamie Danielson --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index 5d868da893..4067de95d3 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -194,6 +194,6 @@ Instrumentation may add additional patch/unpatch messages for specific functions - 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. - 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 a 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. +- 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. The cases above are not covered by the base class and offer additional context to the user trouble shooting an issue with the instrumentation. From 855d264bada71cc103b8c7351a2f3ceba030c7ae Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Tue, 30 Apr 2024 05:10:25 +0300 Subject: [PATCH 18/20] Update GUIDELINES.md Co-authored-by: Jamie Danielson --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index 4067de95d3..e292784a9e 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -196,4 +196,4 @@ Instrumentation may add additional patch/unpatch messages for specific functions - 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 a 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 lambda framework and exposes them for troubleshooting. -The cases above are not covered by the base class and offer additional context to the user trouble shooting an issue with the instrumentation. +The cases above are not covered by the base class and offer additional context to the user troubleshooting an issue with the instrumentation. From 4bb5e1646464666221158074a6aac53fab42c485 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Wed, 1 May 2024 09:30:27 +0300 Subject: [PATCH 19/20] Update GUIDELINES.md Co-authored-by: Trent Mick --- GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index e292784a9e..51c3f6af62 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -174,7 +174,7 @@ The diag channel can be used to troubleshoot issues with instrumentation package 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. +- 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. It can also be useful to know when the instrumentation is loaded and patched, to understand the order of operations in the application. From 0ade21f1b5d71985696ec165ada1eef1d989b1de Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Wed, 1 May 2024 09:33:59 +0300 Subject: [PATCH 20/20] fix: name of diag in CHANGELOG --- GUIDELINES.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/GUIDELINES.md b/GUIDELINES.md index 51c3f6af62..04bc219b14 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -165,9 +165,9 @@ To support this use case, you can choose one of the following options: ... ``` -## Diag Channel +## Diag Logging -The diag channel can be used to troubleshoot issues with instrumentation packages. +The OpenTelemetry diagnostic logging channel can be used to troubleshoot issues with instrumentation packages. ### Patching Messages @@ -178,7 +178,7 @@ When OpenTelemetry is installed in a user application, and expected spans are mi 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: +Instrumentation packages should use the `@opentelemetry/instrumentation` package `InstrumentationBase` 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 { @@ -193,7 +193,7 @@ Instrumentation should not add additional debug messages for triggering the patc 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. `aws-lambda` will abort 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 a hook is added to the fastify app instance, which is patched from `moduleExports`. +- 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`. - 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. The cases above are not covered by the base class and offer additional context to the user troubleshooting an issue with the instrumentation.