From 832eb021408c57ac7c8f8ed614501a0c3d5188e4 Mon Sep 17 00:00:00 2001
From: Timur Zlobin <mysquadstory@gmail.com>
Date: Mon, 3 Feb 2025 18:51:05 +0300
Subject: [PATCH] feat(otel): expose SDK instance from registerOTel

This change allows users to properly manage OpenTelemetry SDK lifecycle
by exposing the SDK instance from registerOTel function.

Previously, there was no way to properly shutdown the SDK
which could lead to lost telemetry data during application shutdown.
Now users can store the SDK instance and call shutdown when needed.

Example:

```typescript
const sdk = registerOTel("service-name");
process.on('SIGTERM', async () => {
  await sdk.shutdown();
});
```
---
 packages/otel/README.md    | 19 ++++++++++++-------
 packages/otel/src/index.ts |  4 +++-
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/packages/otel/README.md b/packages/otel/README.md
index 42cf268..ba2c98b 100644
--- a/packages/otel/README.md
+++ b/packages/otel/README.md
@@ -20,8 +20,13 @@ To configure OpenTelemetry SDK, call the `registerOTel` in the `instrumentation.
 import { registerOTel } from "@vercel/otel";
 
 export function register() {
-  // Register the OpenTelemetry.
-  registerOTel("your-service-name");
+  // Register the OpenTelemetry and get SDK instance
+  const sdk = registerOTel("your-service-name");
+
+  // Optionally store SDK instance for shutdown
+  process.on("SIGTERM", async () => {
+    await sdk.shutdown();
+  });
 }
 ```
 
@@ -36,15 +41,15 @@ const span = trace.getTracer("your-component").startSpan("your-operation");
 
 ## 📖 API Reference
 
-### `registerOTel(serviceName: string)`
+### `registerOTel(serviceName: string): Sdk`
 
-Registers the OpenTelemetry SDK with the specified service name and the default configuration.
+Registers the OpenTelemetry SDK with the specified service name and the default configuration. Returns SDK instance for managing lifecycle.
 
-- `serviceName`: The name of your service, used as the app name in many OpenTelemetry backends.
+- serviceName: The name of your service, used as the app name in many OpenTelemetry backends.
 
-### `registerOTel(config: Configuration)`
+### `registerOTel(config: Configuration): Sdk`
 
-Registers the OpenTelemetry SDK with the specified configuration. Configuration options include:
+Registers the OpenTelemetry SDK with the specified configuration. Returns SDK instance for managing lifecycle. Configuration options include:
 
 - `serviceName`: The name of your service, used as the app name in many OpenTelemetry backends.
 - `attributes`: The resource attributes. By default, `@vercel/otel` configures relevant Vercel attributes based on [the environment](https://vercel.com/docs/projects/environment-variables/system-environment-variables), such as `env`, `vercel.runtime`, `vercel.host`, etc.
diff --git a/packages/otel/src/index.ts b/packages/otel/src/index.ts
index 5cece21..00299f0 100644
--- a/packages/otel/src/index.ts
+++ b/packages/otel/src/index.ts
@@ -29,7 +29,7 @@ export {
  */
 export function registerOTel(
   optionsOrServiceName?: Configuration | string
-): void {
+): Sdk {
   let options: Configuration;
   if (!optionsOrServiceName) {
     options = {};
@@ -40,4 +40,6 @@ export function registerOTel(
   }
   const sdk = new Sdk(options);
   sdk.start();
+
+  return sdk;
 }