feat(node-sdk): allow setting additional resource attributes (#198)

Add an optional `initSDK` property that lets one set additional, user controlled resource attributes in the node SDK. This feature exists in the browser SDK already.

Author: dhable

.changeset/long-gifts-nail.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/node-opentelemetry': minor
+---
+
+Allows setting user defined resource attributes when initializing the SDK.

packages/node-opentelemetry/README.md

@@ -106,6 +106,12 @@ import { initSDK } from '@hyperdx/node-opentelemetry';
 initSDK({
   consoleCapture: true, // optional, default: true
   additionalInstrumentations: [], // optional, default: []
+  additionalResourceAttributes: { // optional, default: {}
+    // Add custom resource attributes to all telemetry data
+    'environment': 'production',
+    'deployment.version': '1.0.0',
+    'custom.attribute': 'value'
+  },
 });
 
 // Other instrumentation code...
@@ -164,6 +170,30 @@ app.use((req, res, next) => {
 
 ### (Optional) Advanced Instrumentation Configuration
 
+#### Adding Custom Resource Attributes
+
+Resource attributes are key-value pairs that describe the resource (service/application) producing telemetry data. These attributes are attached to all traces, metrics, and logs exported from your application. Common use cases include adding environment information, deployment versions, or custom metadata for filtering and grouping telemetry data.
+
+When using manual instrumentation with `initSDK`, you can add custom resource attributes using the `additionalResourceAttributes` parameter:
+
+```ts
+import { initSDK } from '@hyperdx/node-opentelemetry';
+
+initSDK({
+  additionalResourceAttributes: {
+    'deployment.environment': process.env.NODE_ENV || 'development',
+    'service.version': process.env.APP_VERSION || '0.0.0',
+    'service.namespace': 'my-namespace',
+    'cloud.region': process.env.AWS_REGION,
+    // Add any custom attributes your organization needs
+    'team.name': 'backend-team',
+    'feature.flag': 'new-checkout-flow'
+  },
+});
+```
+
+These attributes will be included with all telemetry data sent to HyperDX, making it easier to filter and analyze your observability data. For standard attribute names, refer to the [OpenTelemetry Resource Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/).
+
 #### Adding Additional 3rd-Party Instrumentation Packages
 
 When manually instrumenting the SDK, use the `additionalInstrumentations` key to create an array of additional 3rd-party instrumentations. Check [here](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations) to see the current automatically instrumented packages.

packages/node-opentelemetry/src/__tests__/otel.test.ts

@@ -18,6 +18,22 @@ describe('otel', () => {
     shutdown();
   });
 
+  it('should be able to initialize the SDK with initSDK using additional resource attributes', async () => {
+    initSDK({
+      apiKey: 'blabla',
+      advancedNetworkCapture: true,
+      consoleCapture: true,
+      additionalResourceAttributes: {
+        'cloud.region': 'us-east-2',
+        'cloud.availability_zone': 'us-east-2a',
+      },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    shutdown();
+  });
+
   it('should be able to initialize the SDK with init', async () => {
     init({
       apiKey: 'blabla',

packages/node-opentelemetry/src/otel.ts

@@ -12,7 +12,7 @@ import {
   InstrumentationModuleDefinition,
 } from '@opentelemetry/instrumentation';
 import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node';
-import { Resource } from '@opentelemetry/resources';
+import { Resource, ResourceAttributes } from '@opentelemetry/resources';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import cliSpinners from 'cli-spinners';
@@ -58,6 +58,7 @@ const IS_LOCAL = env.NODE_ENV === 'development' || !env.NODE_ENV;
 
 export type SDKConfig = {
   additionalInstrumentations?: InstrumentationBase[];
+  additionalResourceAttributes?: ResourceAttributes;
   advancedNetworkCapture?: boolean;
   apiKey?: string;
   betaMode?: boolean;
@@ -331,6 +332,7 @@ export const initSDK = (config: SDKConfig) => {
 
   sdk = new NodeSDK({
     resource: new Resource({
+      ...config.additionalResourceAttributes,
       // https://opentelemetry.io/docs/specs/semconv/resource/#telemetry-sdk-experimental
       'telemetry.distro.name': 'hyperdx',
       'telemetry.distro.version': PKG_VERSION,