diff --git a/.changeset/long-gifts-nail.md b/.changeset/long-gifts-nail.md new file mode 100644 index 00000000..728013b5 --- /dev/null +++ b/.changeset/long-gifts-nail.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/node-opentelemetry': minor +--- + +Allows setting user defined resource attributes when initializing the SDK. diff --git a/packages/node-opentelemetry/README.md b/packages/node-opentelemetry/README.md index 707c2694..60429ea3 100644 --- a/packages/node-opentelemetry/README.md +++ b/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. diff --git a/packages/node-opentelemetry/src/__tests__/otel.test.ts b/packages/node-opentelemetry/src/__tests__/otel.test.ts index 73434b5a..2cfba006 100644 --- a/packages/node-opentelemetry/src/__tests__/otel.test.ts +++ b/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', diff --git a/packages/node-opentelemetry/src/otel.ts b/packages/node-opentelemetry/src/otel.ts index 6b29c23c..aaa4d93e 100644 --- a/packages/node-opentelemetry/src/otel.ts +++ b/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,