docs: specify semantic conventions

open-telemetry · Apr 4, 2024 · 1106e97 · 1106e97
1 parent 2484ef6
commit 1106e97
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 14 deletions.
diff --git a/packages/opentelemetry-host-metrics/README.md b/packages/opentelemetry-host-metrics/README.md
@@ -20,30 +20,63 @@ npm install --save @opentelemetry/host-metrics
 ## Usage
 
 ```javascript
-const { MeterProvider } = require('@opentelemetry/sdk-metrics');
-const { HostMetrics } = require('@opentelemetry/host-metrics');
-const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
+const { MeterProvider } | require('@opentelemetry/sdk-metrics');
+const { HostMetrics } | require('@opentelemetry/host-metrics');
+const { PrometheusExporter } | require('@opentelemetry/exporter-prometheus');
 
-const exporter = new PrometheusExporter(
+const exporter | new PrometheusExporter(
   {
     startServer: true
-  }, () => {
+  }| () => {
     console.log('prometheus scrape endpoint: http://localhost:9464/metrics')
   }
 );
 
-const meterProvider = new MeterProvider();
+const meterProvider | new MeterProvider();
 meterProvider.addMetricReader(exporter);
 
-const hostMetrics = new HostMetrics({ meterProvider, name: 'example-host-metrics' });
+const hostMetrics | new HostMetrics({ meterProvider| name: 'example-host-metrics' });
 hostMetrics.start();
 ```
 
+## Semantic Conventions
+
+This package uses Semantic Conventions [Version 1.25.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.25.0/docs/system).
+As for now the Semantic Conventions are bundled in this package but eventually will be imported from `@opentelemetry/semantic-conventions` package when it is updated to latest version.
+Ref: [opentelemetry-js/issues/4235](https://github.com/open-telemetry/opentelemetry-js/issues/4235)
+
+Metrics collected:
+
+| Metric                      | Short Description                                         | Notes |
+| --------------------------- | --------------------------------------------------------- | ----- |
+| `system.cpu.time`           | Seconds each logical CPU spent on each mode               |       |
+| `system.cpu.utilization`    | Difference in system.cpu.time since the last measurement  |       |
+| `system.memory.usage`       | Reports memory in use by state                            |       |
+| `system.memory.utilization` |                                                           |       |
+| `system.network.dropped`    | Count of packets that are dropped                         |       |
+| `system.network.errors`     | Count of network errors detected                          |       |
+| `system.network.io`         |                                                           |       |
+| `process.cpu.time`          | Total CPU seconds                                         |       |
+| `process.cpu.utilization`   | Difference in process.cpu.time since the last measurement |       |
+| `process.memory.usage`      | The amount of physical memory in use                      |       |
+
+Attributes collected:
+
+| Metric                      | Short Description                  | Notes |
+| --------------------------- | ---------------------------------- | ----- |
+| `system.cpu.logical_number` | The logical CPU number             |       |
+| `system.cpu.state`          | The state of the CPU               |       |
+| `system.memory.state`       | The memory state                   |       |
+| `system.device`             | The device identifier              |       |
+| `network.io.direction`      | The network IO operation direction |       |
+| `system.network.state`      | The network state                  |       |
+| `process.cpu.state`         | The CPU state                      |       |
+
 ## Useful links
 
-* For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+* For more information on OpenTelemetry| visit: <https://opentelemetry.io/>
 * For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
-* For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
+* For help or feedback on this project| join us in [GitHub Discussions][discussions-url]
 
 ## License
 

diff --git a/packages/opentelemetry-host-metrics/src/enum.ts b/packages/opentelemetry-host-metrics/src/enum.ts
@@ -32,7 +32,7 @@ export enum ATTRIBUTE_NAMES {
   SYSTEM_CPU_STATE = 'system.cpu.state',
   SYSTEM_MEMORY_STATE = 'system.memory.state',
   SYSTEM_DEVICE = 'system.device',
-  SYSTEM_NETWORK_DIRECTION = 'system.network.direction',
+  NETWORK_NETWORK_DIRECTION = 'network.io.direction',
   SYSTEM_NETWORK_STATE = 'system.network.state',
   PROCESS_CPU_STATE = 'process.cpu.state',
 }

diff --git a/packages/opentelemetry-host-metrics/src/metric.ts b/packages/opentelemetry-host-metrics/src/metric.ts
@@ -151,7 +151,7 @@ export class HostMetrics extends BaseMetrics {
     networkUsages: Systeminformation.NetworkStatsData[]
   ): void {
     const deviceAttr = ATTRIBUTE_NAMES.SYSTEM_DEVICE;
-    const directionAttr = ATTRIBUTE_NAMES.SYSTEM_NETWORK_DIRECTION;
+    const directionAttr = ATTRIBUTE_NAMES.NETWORK_NETWORK_DIRECTION;
 
     for (let i = 0, j = networkUsages.length; i < j; i++) {
       const networkUsage = networkUsages[i];

diff --git a/packages/opentelemetry-host-metrics/test/metric.test.ts b/packages/opentelemetry-host-metrics/test/metric.test.ts
@@ -38,8 +38,8 @@ class TestMetricReader extends MetricReader {
   public override selectAggregationTemporality(): AggregationTemporality {
     return AggregationTemporality.CUMULATIVE;
   }
-  protected async onForceFlush(): Promise<void> {}
-  protected async onShutdown(): Promise<void> {}
+  protected async onForceFlush(): Promise<void> { }
+  protected async onShutdown(): Promise<void> { }
 }
 
 let countSI = 0;
@@ -169,7 +169,7 @@ describe('Host Metrics', () => {
     const sysCpuNumAttr = ATTRIBUTE_NAMES.SYSTEM_CPU_LOGICAL_NUMBER;
     const sysMemStateAttr = ATTRIBUTE_NAMES.SYSTEM_MEMORY_STATE;
     const sysDeviceAttr = ATTRIBUTE_NAMES.SYSTEM_DEVICE;
-    const sysNetDirAttr = ATTRIBUTE_NAMES.SYSTEM_NETWORK_DIRECTION;
+    const sysNetDirAttr = ATTRIBUTE_NAMES.NETWORK_NETWORK_DIRECTION;
     const procCpuStateAttr = ATTRIBUTE_NAMES.PROCESS_CPU_STATE;
 
     it('should export CPU time metrics', async () => {