CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-opentelemetry--resources

OpenTelemetry SDK resources for representing immutable entities that produce telemetry data

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

resource-detection.mddocs/

Resource Detection

Automatic resource discovery system with built-in detectors for environment variables, host information, operating system details, and process metadata. The detection system provides a pluggable architecture for discovering environment-specific resource attributes.

Capabilities

Resource Detection Coordination

Main function that runs resource detectors and merges their results into a single Resource.

/**
 * Detects resources using the provided detectors and merges results
 * @param config - Optional configuration specifying which detectors to run
 * @returns Merged Resource containing all detected attributes
 */
function detectResources(config?: ResourceDetectionConfig): Resource;

interface ResourceDetectionConfig {
  /** Array of resource detectors to run. If not provided, runs all available detectors */
  detectors?: ResourceDetector[];
}

Usage Examples:

import { 
  detectResources, 
  envDetector, 
  hostDetector, 
  osDetector, 
  processDetector 
} from "@opentelemetry/resources";

// Detect using all available detectors
const allResources = detectResources();

// Detect using specific detectors
const selectedResources = detectResources({
  detectors: [envDetector, hostDetector, osDetector]
});

// Detect using only environment variables
const envOnlyResources = detectResources({
  detectors: [envDetector]
});

console.log(selectedResources.attributes);

Resource Detector Interface

Interface for implementing custom resource detectors.

/**
 * Interface for resource detector implementations
 */
interface ResourceDetector {
  /**
   * Detects resource attributes specific to this detector's domain
   * @param config - Optional detection configuration
   * @returns Detected resource attributes (synchronous)
   */
  detect(config?: ResourceDetectionConfig): DetectedResource;
}

type DetectedResource = {
  /** Detected resource attributes (optional) */
  attributes?: DetectedResourceAttributes;
  /** Optional schema URL for the detected attributes */
  schemaUrl?: string;
};

type DetectedResourceAttributes = Record<string, AttributeValue | Promise<AttributeValue> | undefined>;

Built-in Detectors

Environment Variable Detector

Detects resources from OpenTelemetry environment variables.

/**
 * Detects resources from OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME environment variables
 */
declare const envDetector: ResourceDetector;

Environment Variables:

  • OTEL_RESOURCE_ATTRIBUTES: Comma-separated key=value pairs
  • OTEL_SERVICE_NAME: Service name override

Usage Examples:

import { envDetector, detectResources } from "@opentelemetry/resources";

// Set environment variables
process.env.OTEL_SERVICE_NAME = "my-service";
process.env.OTEL_RESOURCE_ATTRIBUTES = "service.version=1.2.0,deployment.environment=production";

// Detect from environment
const envResource = detectResources({ detectors: [envDetector] });
console.log(envResource.attributes);
// { "service.name": "my-service", "service.version": "1.2.0", "deployment.environment": "production" }

Host Detector (Node.js only)

Detects host-related resource attributes in Node.js environments.

/**
 * Detects host information including hostname, architecture, and host ID
 * Available only in Node.js environments
 */
declare const hostDetector: ResourceDetector;

Detected Attributes:

  • host.name: System hostname
  • host.arch: System architecture (x64, arm64, etc.)
  • host.id: Unique host identifier

Usage Examples:

import { hostDetector, detectResources } from "@opentelemetry/resources";

// Detect host information (Node.js only)
const hostResource = detectResources({ detectors: [hostDetector] });
console.log(hostResource.attributes);
// { "host.name": "server-01", "host.arch": "x64", "host.id": "unique-host-id" }

Operating System Detector (Node.js only)

Detects operating system information in Node.js environments.

/**
 * Detects operating system type and version
 * Available only in Node.js environments  
 */
declare const osDetector: ResourceDetector;

Detected Attributes:

  • os.type: Operating system type (Linux, Windows, Darwin, etc.)
  • os.version: Operating system version

Usage Examples:

import { osDetector, detectResources } from "@opentelemetry/resources";

// Detect OS information (Node.js only)
const osResource = detectResources({ detectors: [osDetector] });
console.log(osResource.attributes);
// { "os.type": "Linux", "os.version": "5.4.0-74-generic" }

Process Detector (Node.js only)

Detects process-related resource attributes in Node.js environments.

/**
 * Detects process information including PID, executable details, and runtime information
 * Available only in Node.js environments
 */
declare const processDetector: ResourceDetector;

Detected Attributes:

  • process.pid: Process ID
  • process.executable.name: Executable name
  • process.executable.path: Executable path
  • process.command: Command used to run the process
  • process.command_args: Command arguments
  • process.runtime.name: Runtime name (nodejs)
  • process.runtime.version: Runtime version
  • process.runtime.description: Runtime description

Usage Examples:

import { processDetector, detectResources } from "@opentelemetry/resources";

// Detect process information (Node.js only)
const processResource = detectResources({ detectors: [processDetector] });
console.log(processResource.attributes);
// {
//   "process.pid": 12345,
//   "process.executable.name": "node",
//   "process.runtime.name": "nodejs",
//   "process.runtime.version": "18.19.0",
//   ...
// }

Service Instance ID Detector (Node.js only)

Detects or generates a unique service instance identifier.

/**
 * Detects or generates a unique service instance ID
 * Available only in Node.js environments
 */
declare const serviceInstanceIdDetector: ResourceDetector;

Detected Attributes:

  • service.instance.id: Unique service instance identifier

Usage Examples:

import { serviceInstanceIdDetector, detectResources } from "@opentelemetry/resources";

// Detect service instance ID (Node.js only)
const instanceResource = detectResources({ detectors: [serviceInstanceIdDetector] });
console.log(instanceResource.attributes);
// { "service.instance.id": "unique-instance-id" }

Platform Differences

Node.js Environment

All detectors are available and provide comprehensive system information:

  • Environment variables (envDetector)
  • Host details (hostDetector)
  • OS information (osDetector)
  • Process details (processDetector)
  • Service instance ID (serviceInstanceIdDetector)

Browser Environment

Limited detection capabilities due to browser security restrictions:

  • Environment variables (envDetector) - limited functionality
  • Host/OS/Process detectors return empty results
  • Service instance ID generates browser-specific identifier

Usage Examples:

import { detectResources, envDetector } from "@opentelemetry/resources";

// Cross-platform detection (adapts to environment)
const resource = detectResources();

// Browser-safe detection
const browserSafeResource = detectResources({
  detectors: [envDetector] // Other detectors will return empty results in browser
});

Custom Detector Implementation

import { ResourceDetector, DetectedResource } from "@opentelemetry/resources";

class CustomDetector implements ResourceDetector {
  async detect(): Promise<DetectedResource> {
    return {
      attributes: {
        "custom.attribute": "custom-value",
        "async.attribute": Promise.resolve("async-value")
      }
    };
  }
}

const customDetector = new CustomDetector();
const resource = detectResources({ detectors: [customDetector] });

No-Operation Detector

A no-operation detector that returns empty attributes, useful for testing or when no detection is needed.

/**
 * A no-operation detector that returns empty resource attributes
 */
declare const noopDetector: ResourceDetector;

Usage Examples:

import { noopDetector, detectResources } from "@opentelemetry/resources";

// Use noop detector (returns empty attributes)
const emptyResource = detectResources({ detectors: [noopDetector] });
console.log(emptyResource.attributes); // {}

Install with Tessl CLI

npx tessl i tessl/npm-opentelemetry--resources

docs

index.md

resource-detection.md

resource-management.md

tile.json