0
# OpenTelemetry Resources
1

2
OpenTelemetry Resources provides utilities for representing immutable entities that produce telemetry data. It includes resource detection capabilities for automatically discovering environment-specific information like host details, process information, and service metadata across Node.js and browser environments.
3

4
## Package Information
5

6
- **Package Name**: @opentelemetry/resources
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @opentelemetry/resources`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Resource, 
16
  detectResources, 
17
  resourceFromAttributes, 
18
  resourceFromDetectedResource,
19
  defaultResource,
20
  emptyResource,
21
  envDetector,
22
  hostDetector,
23
  osDetector,
24
  processDetector,
25
  serviceInstanceIdDetector,
26
  noopDetector,
27
  defaultServiceName
28
} from "@opentelemetry/resources";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { 
35
  detectResources, 
36
  resourceFromAttributes, 
37
  resourceFromDetectedResource,
38
  defaultResource,
39
  emptyResource,
40
  envDetector,
41
  hostDetector,
42
  osDetector,
43
  processDetector,
44
  serviceInstanceIdDetector,
45
  noopDetector,
46
  defaultServiceName
47
} = require("@opentelemetry/resources");
48
```
49

50
## Basic Usage
51

52
```typescript
53
import { 
54
  detectResources, 
55
  resourceFromAttributes, 
56
  resourceFromDetectedResource,
57
  envDetector, 
58
  hostDetector 
59
} from "@opentelemetry/resources";
60

61
// Automatic resource detection
62
const autoDetectedResource = detectResources({
63
  detectors: [envDetector, hostDetector]
64
});
65

66
// Manual resource creation
67
const manualResource = resourceFromAttributes({
68
  "service.name": "my-service",
69
  "service.version": "1.0.0",
70
  "host.name": "production-server"
71
});
72

73
// Create resource from DetectedResource object
74
const detectedResourceObj = {
75
  attributes: {
76
    "deployment.environment": "production",
77
    "service.instance.id": "instance-123"
78
  }
79
};
80
const resourceFromDetected = resourceFromDetectedResource(detectedResourceObj);
81

82
// Merge resources
83
const combinedResource = autoDetectedResource.merge(manualResource).merge(resourceFromDetected);
84

85
// Access resource attributes 
86
console.log(combinedResource.attributes);
87
```
88

89
## Architecture
90

91
OpenTelemetry Resources is built around several key components:
92

93
- **Resource Interface**: Immutable representation of telemetry-producing entities with merge capabilities
94
- **Resource Detection System**: Pluggable detector architecture for automatic environment discovery
95
- **Platform Abstractions**: Environment-specific implementations for Node.js and browser contexts
96
- **Built-in Detectors**: Ready-to-use detectors for common resource attributes (environment variables, host info, process details)
97

98
## Capabilities
99

100
### Resource Management
101

102
Core functionality for creating, manipulating, and accessing resource information.
103

104
```typescript { .api }
105
interface Resource {
106
  readonly asyncAttributesPending?: boolean;
107
  readonly attributes: Attributes;
108
  readonly schemaUrl?: string;
109
  waitForAsyncAttributes?(): Promise<void>;
110
  merge(other: Resource | null): Resource;
111
  getRawAttributes(): RawResourceAttribute[];
112
}
113

114
function resourceFromAttributes(
115
  attributes: DetectedResourceAttributes, 
116
  options?: ResourceOptions
117
): Resource;
118

119
function resourceFromDetectedResource(
120
  detectedResource: DetectedResource,
121
  options?: ResourceOptions
122
): Resource;
123

124
function defaultResource(): Resource;
125

126
function emptyResource(): Resource;
127

128
function defaultServiceName(): string;
129
```
130

131
[Resource Management](./resource-management.md)
132

133
### Resource Detection
134

135
Automatic resource discovery system with built-in detectors for environment variables, host information, operating system details, and process metadata.
136

137
```typescript { .api }
138
function detectResources(config?: ResourceDetectionConfig): Resource;
139

140
interface ResourceDetectionConfig {
141
  detectors?: ResourceDetector[];
142
}
143

144
interface ResourceDetector {
145
  detect(config?: ResourceDetectionConfig): DetectedResource | Promise<DetectedResource>;
146
}
147
```
148

149
[Resource Detection](./resource-detection.md)
150

151
## Types
152

153
```typescript { .api }
154
interface ResourceOptions {
155
  schemaUrl?: string;
156
}
157

158
type DetectedResource = {
159
  attributes?: DetectedResourceAttributes;
160
  schemaUrl?: string;
161
};
162

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

165
type RawResourceAttribute = [string, MaybePromise<AttributeValue | undefined>];
166

167
type MaybePromise<T> = T | Promise<T>;
168

169
type AttributeValue = 
170
  | string 
171
  | number 
172
  | boolean 
173
  | Array<null | undefined | string> 
174
  | Array<null | undefined | number> 
175
  | Array<null | undefined | boolean>;
176

177
type Attributes = Record<string, AttributeValue>;
178
```