Skip to content
This repository was archived by the owner on Oct 3, 2023. It is now read-only.

Commit ed99dcb

Browse files
fabxcfabxc
authored
Add resource specs (#162)
* Add resource specs Signed-off-by: Fabian Reinartz <freinartz@google.com> * Address comments * Add clarifications Signed-off-by: Fabian Reinartz <freinartz@google.com> * Add clarifications Signed-off-by: Fabian Reinartz <freinartz@google.com> * Address comments Signed-off-by: Fabian Reinartz <freinartz@google.com>
1 parent ce47af8 commit ed99dcb

2 files changed

Lines changed: 162 additions & 0 deletions

File tree

‎resource/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# OpenCensus Library Resource Package
2+
This documentation serves to document the "look and feel" of the OpenCensus resource package.
3+
It describes their key types and overall behavior.
4+
5+
The resource library primarily defines a type "Resource" that captures information about the
6+
entity for which stats or traces are recorded. For example, metrics exposed by a Kubernetes
7+
container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
8+
The primary purpose of resources as a first-class concept in the core library is decoupling
9+
of discovery of resource information from exporters. This allows for independent development
10+
of easy customization for users that need to integrate with closed source environments.
11+
12+
13+
## Main APIs
14+
* [Resource](Resource.md)

‎resource/Resource.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Resource API Overview
2+
The resource library primarily defines a type that captures information about the entity
3+
for which stats or traces are reported. It further provides a framework for detection of
4+
resource information from the environment and progressive population as signals propagate
5+
from the core instrumentation library to a backend's exporter.
6+
7+
## Resource type
8+
A `Resource` describes the entity for which a signal was collected through two fields:
9+
* `type`: an optional string which describes a well-known type of resource.
10+
* `labels`: a dictionary of labels with string keys and values that provide information
11+
about the entity.
12+
13+
Type, label keys, and label values MUST contain only printable ASCII (codes between 32
14+
and 126, inclusive) and not exceed 256 characters.
15+
Type and label keys MUST have a length greater than zero. They SHOULD start with a domain
16+
name and separate hierarchies with `/` characters, e.g. `k8s.io/namespace/name`.
17+
18+
Implementations MAY define a `Resource` data type, constructed from the parameters above.
19+
`Resource` MUST have getters for retrieving all the information used in `Resource` definition.
20+
21+
Example in Go:
22+
```go
23+
type Resource {
24+
Type string
25+
Labels map[string]string
26+
}
27+
```
28+
29+
TODO(fabxc): link protobuf definition.
30+
31+
## Populating resources
32+
Resource information MAY be populated at any point between startup of the instrumented
33+
application and passing it to a backend-specific exporter. This explicitly includes
34+
the path through future OpenCensus components such as agents or services.
35+
36+
For example, process-identifying information may be populated through the library while
37+
an agent attaches further labels about the underlying VM, the cluster, or geo-location.
38+
39+
### From environment variables
40+
Population of resource information from environment variables MUST be provided by the
41+
core library. It provides the user with an ubiquitious way to manually provide information
42+
that may not be detectable automatically through available integration libraries.
43+
44+
Two environment variables are used:
45+
* `OC_RESOURCE_TYPE`: defines the resource type. Leading and trailing whitespaces are trimmed.
46+
* `OC_RESOURCE_LABELS`: defines resource labels as a comma-seperated list of key/value pairs
47+
(`[ <key>="value" [ ,<key>="<value>" ... ] ]`). `"` characters in values MUST be escaped with `\`.
48+
49+
For example:
50+
* `OC_RESOURCE_TYPE=k8s.io/container`
51+
* `OC_RESOURCE_LABELS=k8s.io/pod/name="pod-xyz-123",k8s.io/container/name="c1",k8s.io/namespace/name="default"`
52+
53+
Population from environment variables MUST be the first applied detection process unless
54+
the user explicitly overwrites this behavior.
55+
56+
### Auto-detection
57+
Auto-detection of resource information in specific environments, e.g. specific cloud
58+
vendors, MUST be implemented outside of the core libraries in third party or
59+
[census-ecosystem][census-ecosystem] repositories.
60+
61+
### Merging
62+
As different mechanisms are run to gain information about a resource, their information
63+
has to be merged into a single resulting resource.
64+
Already set labels or type fields MUST NOT be overwritten. Label key namespaceing SHOULD
65+
be used to prevent collisions across different resource detection steps.
66+
67+
### Detectors
68+
To make auto-detection implementations easy to use, the core resource package SHOULD define
69+
an interface to retrieve resource information. Additionally, helper functionality MAY be
70+
provided to effectively make use of this interface.
71+
The exact shape of those interfaces and helpers SHOULD be idiomatic to the respective language.
72+
73+
Example in Go:
74+
75+
```go
76+
type Detector func(context.Context) (*Resource, error)
77+
78+
// Returns a detector that runs all input detectors sequentially and merges their results.
79+
func ChainedDetector(...Detector) Detector
80+
```
81+
82+
### Updates
83+
OpenCensus's resource representation is focused on providing static, uniquely identifying
84+
information and thus those mutable attributes SHOULD NOT be included in the resource
85+
representation.
86+
Resource type and labels MUST NOT be mutated after initialization. Any changes MUST be
87+
effectively be treated as a different resource and any associated signal state MUST be reset.
88+
89+
## Exporter translation
90+
A resource object MUST NOT be mutated further once it is passed to a backend-specific exporter.
91+
From the provided resource information, the exporter MAY transform, drop, or add information
92+
to build the resource identifying data type specific to its backend.
93+
If the passed resource does not contain sufficient information, an exporter MAY drop
94+
signal data entirely, if no sufficient resource information is provided to perform a correct
95+
write.
96+
97+
For example, from a resource object
98+
99+
```javascript
100+
{
101+
"type": "k8s.io/container",
102+
"labels": {
103+
// Populated from VM environment through auto-detection library.
104+
"cloud.google.com/gce/instance_id": "instance1",
105+
"cloud.google.com/zone": "eu-west2-a",
106+
"cloud.google.com/project_id": "project1",
107+
"cloud.google.com/gce/attributes/cluster_name": "cluster1",
108+
// Populated through OpenCensus resource environment variables.
109+
"k8s.io/namespace/name": "ns1",
110+
"k8s.io/pod/name": "pod1",
111+
"k8s.io/container/name": "container1",
112+
},
113+
}
114+
```
115+
116+
an exporter for Stackdriver would create the following "monitored resource", which is a
117+
resource type with well-known identifiers specific to its API:
118+
119+
```javascript
120+
{
121+
"type": "k8s_container",
122+
"labels": {
123+
"project_id": "project1",
124+
"location": "eu-west2-a",
125+
"cluster_name": "cluster1",
126+
"namespace_name": "ns1",
127+
"pod_name": "pod1",
128+
"container_name": "container1",
129+
},
130+
}
131+
```
132+
133+
For another, hyopthetical, backend a simple unique identifier might be constructed instead
134+
by its exporter:
135+
136+
```
137+
cluster1/ns1/pod1/container1
138+
```
139+
140+
Exporter libraries MAY provide a default translation for well-known input resource types and labels.
141+
Those would generally be based on community-supported detection integrations maintained in the
142+
[census-ecosystem][census-ecosystem] organisation.
143+
144+
Additionally, exporters SHOULD provide configuration hooks for users to provide their own
145+
translation unless the exporter's backend does not support resources at all. For such backends,
146+
exporters SHOULD allow attaching converting resource labels to metric tags.
147+
148+
[census-ecosystem]: https://github.com/census-ecosystem

0 commit comments

Comments
 (0)