Merge pull request #239 from yandex-cloud/otel

OTEL tracing support

Author: DavyJohnes

README.md

@@ -57,6 +57,24 @@ const response = await cloudServiceClient.list(cloudService.ListCloudsRequest.fr
 }));
 ```
 
+### Tracing (OpenTelemetry)
+
+The SDK can wrap every gRPC call in an OpenTelemetry span via [`nice-grpc-opentelemetry`](https://www.npmjs.com/package/nice-grpc-opentelemetry).
+Install the peer packages and pass `tracing: true`:
+
+```bash
+npm install @opentelemetry/api nice-grpc-opentelemetry
+```
+
+```typescript
+import { Session } from '@yandex-cloud/nodejs-sdk';
+
+const session = new Session({ iamToken: 'YOUR_TOKEN', tracing: true });
+```
+
+A span is produced per RPC attempt (i.e. inside the SDK's retry loop), and trace context is propagated via gRPC metadata using the OpenTelemetry global propagator.
+See [`examples/opentelemetry.ts`](./examples/opentelemetry.ts) for a runnable end-to-end setup.
+
 Check [examples](./examples) directory for more examples.
 
 To run example scripts, you should execute the following commands:

examples/opentelemetry.ts

@@ -0,0 +1,29 @@
+import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { Session } from '@yandex-cloud/nodejs-sdk';
+import { cloudService } from '@yandex-cloud/nodejs-sdk/resourcemanager-v1';
+import { getEnv } from './utils/get-env';
+import { log } from './utils/logger';
+
+const IAM_TOKEN = getEnv('YC_IAM_TOKEN');
+
+const provider = new NodeTracerProvider({
+    spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
+});
+
+provider.register();
+
+(async () => {
+    const session = new Session({ iamToken: IAM_TOKEN, tracing: true });
+    const client = session.client(cloudService.CloudServiceClient);
+
+    const response = await client.list(
+        cloudService.ListCloudsRequest.fromPartial({ pageSize: 200 }),
+    );
+
+    for (const cloud of response.clouds) {
+        log(`Found cloud id = ${cloud.id}, name = ${cloud.name}`);
+    }
+
+    await provider.shutdown();
+})();