0
# Resource Detection
1

2
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.
3

4
## Capabilities
5

6
### Resource Detection Coordination
7

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

10
```typescript { .api }
11
/**
12
 * Detects resources using the provided detectors and merges results
13
 * @param config - Optional configuration specifying which detectors to run
14
 * @returns Merged Resource containing all detected attributes
15
 */
16
function detectResources(config?: ResourceDetectionConfig): Resource;
17

18
interface ResourceDetectionConfig {
19
  /** Array of resource detectors to run. If not provided, runs all available detectors */
20
  detectors?: ResourceDetector[];
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { 
28
  detectResources, 
29
  envDetector, 
30
  hostDetector, 
31
  osDetector, 
32
  processDetector 
33
} from "@opentelemetry/resources";
34

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

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

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

48
console.log(selectedResources.attributes);
49
```
50

51
### Resource Detector Interface
52

53
Interface for implementing custom resource detectors.
54

55
```typescript { .api }
56
/**
57
 * Interface for resource detector implementations
58
 */
59
interface ResourceDetector {
60
  /**
61
   * Detects resource attributes specific to this detector's domain
62
   * @param config - Optional detection configuration
63
   * @returns Detected resource attributes (synchronous)
64
   */
65
  detect(config?: ResourceDetectionConfig): DetectedResource;
66
}
67

68
type DetectedResource = {
69
  /** Detected resource attributes (optional) */
70
  attributes?: DetectedResourceAttributes;
71
  /** Optional schema URL for the detected attributes */
72
  schemaUrl?: string;
73
};
74

75
type DetectedResourceAttributes = Record<string, AttributeValue | Promise<AttributeValue> | undefined>;
76
```
77

78
## Built-in Detectors
79

80
### Environment Variable Detector
81

82
Detects resources from OpenTelemetry environment variables.
83

84
```typescript { .api }
85
/**
86
 * Detects resources from OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME environment variables
87
 */
88
declare const envDetector: ResourceDetector;
89
```
90

91
**Environment Variables:**
92
- `OTEL_RESOURCE_ATTRIBUTES`: Comma-separated key=value pairs
93
- `OTEL_SERVICE_NAME`: Service name override
94

95
**Usage Examples:**
96

97
```typescript
98
import { envDetector, detectResources } from "@opentelemetry/resources";
99

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

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

110
### Host Detector (Node.js only)
111

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

114
```typescript { .api }
115
/**
116
 * Detects host information including hostname, architecture, and host ID
117
 * Available only in Node.js environments
118
 */
119
declare const hostDetector: ResourceDetector;
120
```
121

122
**Detected Attributes:**
123
- `host.name`: System hostname
124
- `host.arch`: System architecture (x64, arm64, etc.)
125
- `host.id`: Unique host identifier
126

127
**Usage Examples:**
128

129
```typescript
130
import { hostDetector, detectResources } from "@opentelemetry/resources";
131

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

138
### Operating System Detector (Node.js only)
139

140
Detects operating system information in Node.js environments.
141

142
```typescript { .api }
143
/**
144
 * Detects operating system type and version
145
 * Available only in Node.js environments  
146
 */
147
declare const osDetector: ResourceDetector;
148
```
149

150
**Detected Attributes:**
151
- `os.type`: Operating system type (Linux, Windows, Darwin, etc.)
152
- `os.version`: Operating system version
153

154
**Usage Examples:**
155

156
```typescript
157
import { osDetector, detectResources } from "@opentelemetry/resources";
158

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

165
### Process Detector (Node.js only)
166

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

169
```typescript { .api }
170
/**
171
 * Detects process information including PID, executable details, and runtime information
172
 * Available only in Node.js environments
173
 */
174
declare const processDetector: ResourceDetector;
175
```
176

177
**Detected Attributes:**
178
- `process.pid`: Process ID
179
- `process.executable.name`: Executable name
180
- `process.executable.path`: Executable path
181
- `process.command`: Command used to run the process
182
- `process.command_args`: Command arguments
183
- `process.runtime.name`: Runtime name (nodejs)
184
- `process.runtime.version`: Runtime version
185
- `process.runtime.description`: Runtime description
186

187
**Usage Examples:**
188

189
```typescript
190
import { processDetector, detectResources } from "@opentelemetry/resources";
191

192
// Detect process information (Node.js only)
193
const processResource = detectResources({ detectors: [processDetector] });
194
console.log(processResource.attributes);
195
// {
196
//   "process.pid": 12345,
197
//   "process.executable.name": "node",
198
//   "process.runtime.name": "nodejs",
199
//   "process.runtime.version": "18.19.0",
200
//   ...
201
// }
202
```
203

204
### Service Instance ID Detector (Node.js only)
205

206
Detects or generates a unique service instance identifier.
207

208
```typescript { .api }
209
/**
210
 * Detects or generates a unique service instance ID
211
 * Available only in Node.js environments
212
 */
213
declare const serviceInstanceIdDetector: ResourceDetector;
214
```
215

216
**Detected Attributes:**
217
- `service.instance.id`: Unique service instance identifier
218

219
**Usage Examples:**
220

221
```typescript
222
import { serviceInstanceIdDetector, detectResources } from "@opentelemetry/resources";
223

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

230
## Platform Differences
231

232
### Node.js Environment
233
All detectors are available and provide comprehensive system information:
234
- Environment variables (envDetector)
235
- Host details (hostDetector) 
236
- OS information (osDetector)
237
- Process details (processDetector)
238
- Service instance ID (serviceInstanceIdDetector)
239

240
### Browser Environment
241
Limited detection capabilities due to browser security restrictions:
242
- Environment variables (envDetector) - limited functionality
243
- Host/OS/Process detectors return empty results
244
- Service instance ID generates browser-specific identifier
245

246
**Usage Examples:**
247

248
```typescript
249
import { detectResources, envDetector } from "@opentelemetry/resources";
250

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

254
// Browser-safe detection
255
const browserSafeResource = detectResources({
256
  detectors: [envDetector] // Other detectors will return empty results in browser
257
});
258
```
259

260
## Custom Detector Implementation
261

262
```typescript
263
import { ResourceDetector, DetectedResource } from "@opentelemetry/resources";
264

265
class CustomDetector implements ResourceDetector {
266
  async detect(): Promise<DetectedResource> {
267
    return {
268
      attributes: {
269
        "custom.attribute": "custom-value",
270
        "async.attribute": Promise.resolve("async-value")
271
      }
272
    };
273
  }
274
}
275

276
const customDetector = new CustomDetector();
277
const resource = detectResources({ detectors: [customDetector] });
278
```
279

280
### No-Operation Detector
281

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

284
```typescript { .api }
285
/**
286
 * A no-operation detector that returns empty resource attributes
287
 */
288
declare const noopDetector: ResourceDetector;
289
```
290

291
**Usage Examples:**
292

293
```typescript
294
import { noopDetector, detectResources } from "@opentelemetry/resources";
295

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