0
# Resource Management
1

2
Core functionality for creating, manipulating, and accessing resource information. Resources represent immutable entities that produce telemetry data, containing attributes that describe the environment, service, host, and other relevant metadata.
3

4
## Capabilities
5

6
### Resource Creation from Attributes
7

8
Creates a Resource instance from a set of attributes, with optional configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a Resource instance from detected resource attributes
13
 * @param attributes - Resource attributes that may contain promises
14
 * @param options - Optional configuration including schema URL
15
 * @returns Resource instance with the provided attributes
16
 */
17
function resourceFromAttributes(
18
  attributes: DetectedResourceAttributes, 
19
  options?: ResourceOptions
20
): Resource;
21

22
interface ResourceOptions {
23
  /** Schema URL for the resource attributes */
24
  schemaUrl?: string;
25
}
26

27
type DetectedResourceAttributes = Record<string, AttributeValue | Promise<AttributeValue> | undefined>;
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { resourceFromAttributes } from "@opentelemetry/resources";
34

35
// Simple resource creation
36
const resource = resourceFromAttributes({
37
  "service.name": "my-api",
38
  "service.version": "2.1.0",
39
  "deployment.environment": "production"
40
});
41

42
// Resource with schema URL
43
const resourceWithSchema = resourceFromAttributes({
44
  "service.name": "my-api",
45
  "host.name": "server-01"
46
}, {
47
  schemaUrl: "https://opentelemetry.io/schemas/1.9.0"
48
});
49

50
// Resource with async attributes
51
const resourceWithAsync = resourceFromAttributes({
52
  "service.name": "my-api",
53
  "host.id": Promise.resolve("unique-host-id"),
54
  "process.pid": Promise.resolve(process.pid)
55
});
56
```
57

58
### Resource Creation from DetectedResource
59

60
Creates a Resource instance from a DetectedResource object, with optional configuration.
61

62
```typescript { .api }
63
/**
64
 * Creates a Resource instance from a DetectedResource object
65
 * @param detectedResource - DetectedResource object containing attributes and optional schema URL
66
 * @param options - Optional configuration including schema URL override
67
 * @returns Resource instance with the provided attributes
68
 */
69
function resourceFromDetectedResource(
70
  detectedResource: DetectedResource,
71
  options?: ResourceOptions
72
): Resource;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
import { resourceFromDetectedResource } from "@opentelemetry/resources";
79

80
// Create resource from DetectedResource object
81
const detectedResource = {
82
  attributes: {
83
    "service.name": "detected-service",
84
    "host.name": "auto-detected-host"
85
  },
86
  schemaUrl: "https://opentelemetry.io/schemas/1.9.0"
87
};
88

89
const resource = resourceFromDetectedResource(detectedResource);
90

91
// Override schema URL
92
const resourceWithOverride = resourceFromDetectedResource(detectedResource, {
93
  schemaUrl: "https://opentelemetry.io/schemas/1.10.0"
94
});
95
```
96

97
### Default Resource Creation
98

99
Creates a resource with SDK information and default attributes.
100

101
```typescript { .api }
102
/**
103
 * Creates a default resource containing SDK information
104
 * @returns Resource with default SDK attributes
105
 */
106
function defaultResource(): Resource;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
import { defaultResource } from "@opentelemetry/resources";
113

114
// Get default resource with SDK info
115
const sdkResource = defaultResource();
116
console.log(sdkResource.attributes);
117
// Contains telemetry.sdk.name, telemetry.sdk.language, telemetry.sdk.version
118
```
119

120
### Empty Resource Creation
121

122
Creates an empty resource with no attributes.
123

124
```typescript { .api }
125
/**
126
 * Creates an empty resource with no attributes
127
 * @returns Empty Resource instance
128
 */
129
function emptyResource(): Resource;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { emptyResource } from "@opentelemetry/resources";
136

137
// Create empty resource as a base for building
138
const baseResource = emptyResource();
139
const customResource = baseResource.merge(resourceFromAttributes({
140
  "service.name": "custom-service"
141
}));
142
```
143

144
### Default Service Name
145

146
Returns platform-specific default service name.
147

148
```typescript { .api }
149
/**
150
 * Returns the default service name for the current platform
151
 * @returns Default service name string
152
 */
153
function defaultServiceName(): string;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { defaultServiceName } from "@opentelemetry/resources";
160

161
// Get platform-specific default service name
162
const serviceName = defaultServiceName();
163
console.log(serviceName); // "unknown_service:node" on Node.js, "unknown_service" on browser
164
```
165

166
### Resource Interface
167

168
The core Resource interface providing access to attributes and merge capabilities.
169

170
```typescript { .api }
171
/**
172
 * Represents an immutable resource with attributes describing a telemetry source
173
 */
174
interface Resource {
175
  /** Indicates if there are pending asynchronous attributes */
176
  readonly asyncAttributesPending?: boolean;
177
  /** Resource attributes as key-value pairs */
178
  readonly attributes: Attributes;
179
  /** Optional schema URL for the resource */
180
  readonly schemaUrl?: string;
181
  
182
  /** 
183
   * Waits for all asynchronous attributes to resolve
184
   * @returns Promise that resolves when all async attributes are ready
185
   */
186
  waitForAsyncAttributes?(): Promise<void>;
187
  
188
  /**
189
   * Merges this resource with another resource, with the other resource taking precedence
190
   * @param other - Resource to merge with (or null)
191
   * @returns New merged Resource instance
192
   */
193
  merge(other: Resource | null): Resource;
194
  
195
  /**
196
   * Gets raw resource attributes including unresolved promises
197
   * @returns Array of attribute key-value tuples
198
   */
199
  getRawAttributes(): RawResourceAttribute[];
200
}
201

202
type RawResourceAttribute = [string, MaybePromise<AttributeValue | undefined>];
203
type MaybePromise<T> = T | Promise<T>;
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import { resourceFromAttributes, defaultResource } from "@opentelemetry/resources";
210

211
// Create resources
212
const serviceResource = resourceFromAttributes({
213
  "service.name": "my-service",
214
  "service.version": "1.0.0"
215
});
216

217
const hostResource = resourceFromAttributes({
218
  "host.name": "production-server",
219
  "host.arch": "x64"
220
});
221

222
// Merge resources (hostResource attributes take precedence)
223
const combinedResource = serviceResource.merge(hostResource);
224

225
// Access merged attributes
226
console.log(combinedResource.attributes);
227

228
// Handle async attributes
229
const asyncResource = resourceFromAttributes({
230
  "service.name": "my-service",
231
  "dynamic.value": Promise.resolve("computed-value")
232
});
233

234
if (asyncResource.asyncAttributesPending) {
235
  await asyncResource.waitForAsyncAttributes();
236
  console.log(asyncResource.attributes); // Now includes resolved "dynamic.value"
237
}
238

239
// Get raw attributes (including unresolved promises)
240
const rawAttributes = asyncResource.getRawAttributes();
241
console.log(rawAttributes); // [["service.name", "my-service"], ["dynamic.value", Promise<string>]]
242
```
243

244
## Type Definitions
245

246
```typescript { .api }
247
// From @opentelemetry/api
248
type AttributeValue = 
249
  | string 
250
  | number 
251
  | boolean 
252
  | Array<null | undefined | string> 
253
  | Array<null | undefined | number> 
254
  | Array<null | undefined | boolean>;
255

256
type Attributes = Record<string, AttributeValue>;
257
```