Skip to content

Commit 407f615

Browse files
brianphillipsbrianphillips
authored
feat(instrumentation-kafkajs): update semantic conventions (#2752)
Signed-off-by: Brian Phillips <28457+brianphillips@users.noreply.github.com>
1 parent 25b38f3 commit 407f615

File tree

7 files changed

+1232
-157
lines changed

7 files changed

+1232
-157
lines changed

‎package-lock.json

+3-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎plugins/node/instrumentation-kafkajs/README.md

+43-12
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@ npm install --save @opentelemetry/instrumentation-kafkajs
2323

2424
```js
2525
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
26-
const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafkajs');
26+
const {
27+
KafkaJsInstrumentation,
28+
} = require('@opentelemetry/instrumentation-kafkajs');
2729
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
2830

2931
const provider = new NodeTracerProvider();
@@ -42,22 +44,51 @@ registerInstrumentations({
4244

4345
You can set the following:
4446

45-
| Options | Type | Description |
46-
| ---------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
47-
| `producerHook` | `KafkaProducerCustomAttributeFunction` | Function called before a producer message is sent. Allows for adding custom attributes to the span. |
48-
| `consumerHook` | `KafkaConsumerCustomAttributeFunction` | Function called before a consumer message is processed. Allows for adding custom attributes to the span. |
47+
| Options | Type | Description |
48+
| -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
49+
| `producerHook` | `KafkaProducerCustomAttributeFunction` | Function called before a producer message is sent. Allows for adding custom attributes to the span. |
50+
| `consumerHook` | `KafkaConsumerCustomAttributeFunction` | Function called before a consumer message is processed. Allows for adding custom attributes to the span. |
4951

5052
## Semantic Conventions
5153

52-
This package uses `@opentelemetry/semantic-conventions` version `1.24+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)
54+
This package uses `@opentelemetry/semantic-conventions` version `1.30+`, which implements Semantic Convention [Version 1.30.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.30.0/docs/README.md)
5355

54-
Attributes collected:
56+
### Spans Emitted
5557

56-
| Attribute | Short Description |
57-
| -----------------------------| ----------------------------------------------------- |
58-
| `messaging.system` | An identifier for the messaging system being used. |
59-
| `messaging.destination` | The message destination name. |
60-
| `messaging.operation` | A string identifying the kind of messaging operation. |
58+
| KafkaJS Object | Action | Span Kind | Span Name | Operation Type / Name |
59+
| -------------- | -------------------------- | --------- | -------------------------- | --------------------- |
60+
| Consumer | `eachBatch` | Client | `poll <topic-name>` | `receive` / `poll` |
61+
| Consumer | `eachBatch`, `eachMessage` | Consumer | `process <topic-name>` [1] | `process` / `process` |
62+
| Producer | `send` | Producer | `send <topic-name>` | `send` / `send` |
63+
64+
**[1] `process <topic-name>`:** In the context of `eachBatch`, this span will be emitted for each message in the batch but the timing (start, end, duration) will reflect the timing of the batch.
65+
66+
### Metrics Emitted
67+
68+
| KafkaJS Object | Metric Name | Short Description |
69+
| --------------------- | ------------------------------------- | ------------------------------------------------------------ |
70+
| Consumer | `messaging.process.duration` | Duration of processing operation. [1] |
71+
| Consumer | `messaging.client.consumed.messages` | Number of messages that were delivered to the application. |
72+
| Consumer and Producer | `messaging.client.operation.duration` | Number of messages that were delivered to the application. |
73+
| Producer | `messaging.client.sent.messages` | Number of messages producer attempted to send to the broker. |
74+
75+
**[1] `messaging.process.duration`:** In the context of `eachBatch`, this metric will be emitted once for each message but the value reflects the duration of the entire batch.
76+
77+
### Attributes Collected
78+
79+
These attributes are added to both spans and metrics, where possible.
80+
81+
| Attribute | Short Description |
82+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
83+
| `messaging.system` | An identifier for the messaging system being used (i.e. `"kafka"`). |
84+
| `messaging.destination.name` | The message destination name. |
85+
| `messaging.operation.type` | A string identifying the type of messaging operation. |
86+
| `messaging.operation.name` | The system-specific name of the messaging operation. |
87+
| `messaging.operation.name` | The system-specific name of the messaging operation. |
88+
| `messaging.kafka.message.key` | A stringified value representing the key of the Kafka message (if present). |
89+
| `messaging.kafka.message.tombstone` | A boolean that is true if the message is a tombstone. |
90+
| `messaging.kafka.offset` | The offset of a record in the corresponding Kafka partition. |
91+
| `messaging.destination.partition.id` | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. **Note:** only available on producer spans. |
6192

6293
## Useful links
6394

‎plugins/node/instrumentation-kafkajs/package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"types": "build/src/index.d.ts",
77
"repository": "open-telemetry/opentelemetry-js-contrib",
88
"scripts": {
9-
"test": "mocha --require @opentelemetry/contrib-test-utils 'test/**/*.test.ts'",
9+
"test": "nyc mocha --require @opentelemetry/contrib-test-utils 'test/**/*.test.ts'",
1010
"test-all-versions": "tav",
1111
"tdd": "npm run test -- --watch-extensions ts --watch",
1212
"clean": "rimraf build/*",
@@ -58,7 +58,7 @@
5858
},
5959
"dependencies": {
6060
"@opentelemetry/instrumentation": "^0.200.0",
61-
"@opentelemetry/semantic-conventions": "^1.27.0"
61+
"@opentelemetry/semantic-conventions": "^1.30.0"
6262
},
6363
"homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-kafkajs#readme"
6464
}

0 commit comments

Comments
 (0)