Add CloudFoundry Resource Attributes (#624)

Signed-off-by: Karsten Schnitter <[email protected]> Co-authored-by: Joao Grassi <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]>
open-telemetry · Sep 27, 2024 · c120995 · c120995
1 parent b780f48
commit c120995
Show file tree

Hide file tree

Showing 12 changed files with 512 additions and 1 deletion.
diff --git a/.chloggen/cf-resource.yaml b/.chloggen/cf-resource.yaml
@@ -0,0 +1,26 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: cloudfoundry
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adds a resource convention for Cloud Foundry applications and system components.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [622, 624]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Introduces a description for CloudFoundry resources. These can either be
+  applications deployed on the runtime or system components of Cloud Foundry
+  itself. It also extends to the runtime logs and metrics, e.g. Gorouter access
+  logs and container metrics.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -30,6 +30,7 @@ body:
         - area:client
         - area:cloud
         - area:cloudevents
+        - area:cloudfoundry
         - area:code
         - area:container
         - area:cpu

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -22,6 +22,7 @@ body:
         - area:client
         - area:cloud
         - area:cloudevents
+        - area:cloudfoundry
         - area:code
         - area:container
         - area:cpu

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -31,6 +31,7 @@ body:
         - area:client
         - area:cloud
         - area:cloudevents
+        - area:cloudfoundry
         - area:code
         - area:container
         - area:cpu

diff --git a/Makefile b/Makefile
@@ -10,7 +10,7 @@ else
 	SED := sed
 endif
 
-TOOLS_DIR := ./internal/tools
+TOOLS_DIR := $(PWD)/internal/tools
 
 MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -41,6 +41,7 @@ Currently, the following namespaces exist:
 - [Client](client.md)
 - [Cloud](cloud.md)
 - [CloudEvents](cloudevents.md)
+- [CloudFoundry](cloudfoundry.md)
 - [Code](code.md)
 - [Container](container.md)
 - [CPU](cpu.md)

diff --git a/docs/attributes-registry/cloudfoundry.md b/docs/attributes-registry/cloudfoundry.md
@@ -0,0 +1,84 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CloudFoundry
+
+## CloudFoundry Attributes
+
+CloudFoundry resource attributes.
+
+| Attribute                         | Type   | Description                                                                    | Examples                               | Stability                                                        |
+| --------------------------------- | ------ | ------------------------------------------------------------------------------ | -------------------------------------- | ---------------------------------------------------------------- |
+| `cloudfoundry.app.id`             | string | The guid of the application. [1]                                               | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.app.instance.id`    | string | The index of the application instance. 0 when just one instance is active. [2] | `0`; `1`                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.app.name`           | string | The name of the application. [3]                                               | `my-app-name`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.org.id`             | string | The guid of the CloudFoundry org the application is running in. [4]            | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.org.name`           | string | The name of the CloudFoundry organization the app is running in. [5]           | `my-org-name`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.process.id`         | string | The UID identifying the process. [6]                                           | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.process.type`       | string | The type of process. [7]                                                       | `web`                                  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.space.id`           | string | The guid of the CloudFoundry space the application is running in. [8]          | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.space.name`         | string | The name of the CloudFoundry space the application is running in. [9]          | `my-space-name`                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.system.id`          | string | A guid or another name describing the event source. [10]                       | `cf/gorouter`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.system.instance.id` | string | A guid describing the concrete instance of the event source. [11]              | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.application_id`. This is the same value as
+reported by `cf app <app-name> --guid`.
+
+**[2]:** CloudFoundry defines the `instance_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+It is used for logs and metrics emitted by CloudFoundry. It is
+supposed to contain the application instance index for applications
+deployed on the runtime.
+
+Application instrumentation should use the value from environment
+variable `CF_INSTANCE_INDEX`.
+
+**[3]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.application_name`. This is the same value
+as reported by `cf apps`.
+
+**[4]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.org_id`. This is the same value as
+reported by `cf org <org-name> --guid`.
+
+**[5]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.org_name`. This is the same value as
+reported by `cf orgs`.
+
+**[6]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.process_id`. It is supposed to be equal to
+`VCAP_APPLICATION.app_id` for applications deployed to the runtime.
+For system components, this could be the actual PID.
+
+**[7]:** CloudFoundry applications can consist of multiple jobs. Usually the
+main process will be of type `web`. There can be additional background
+tasks or side-cars with different process types.
+
+**[8]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.space_id`. This is the same value as
+reported by `cf space <space-name> --guid`.
+
+**[9]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.space_name`. This is the same value as
+reported by `cf spaces`.
+
+**[10]:** CloudFoundry defines the `source_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+It is used for logs and metrics emitted by CloudFoundry. It is
+supposed to contain the component name, e.g. "gorouter", for
+CloudFoundry components.
+
+When system components are instrumented, values from the
+[Bosh spec](https://bosh.io/docs/jobs/#properties-spec)
+should be used. The `system.id` should be set to
+`spec.deployment/spec.name`.
+
+**[11]:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+It is used for logs and metrics emitted by CloudFoundry. It is
+supposed to contain the vm id for CloudFoundry components.
+
+When system components are instrumented, values from the
+[Bosh spec](https://bosh.io/docs/jobs/#properties-spec)
+should be used. The `system.instance.id` should be set to `spec.id`.
diff --git a/docs/resource/README.md b/docs/resource/README.md
@@ -292,6 +292,7 @@ Attributes defining a running environment (e.g. Operating System, Cloud, Data Ce
 - Deployment:
   - [Deployment Environment](./deployment-environment.md)
   - [Kubernetes](./k8s.md)
+  - [CloudFoundry](./cloudfoundry.md)
 - [Browser](./browser.md)
 
 ## Version attributes

diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md
@@ -0,0 +1,219 @@
+# CloudFoundry
+
+**Status**: [Experimental][DocumentStatus]
+
+Useful resources to understand CloudFoundry metadata:
+
+* <https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION>
+* <https://docs.cloudfoundry.org/devguide/deploy-apps/streaming-logs.html>
+* <https://github.com/cloudfoundry/loggregator-api#v2-envelope>
+* <https://bosh.io/docs/jobs/#properties-spec>
+
+CloudFoundry organizes application deployments (apps) by spaces contained in
+organizations (orgs). Names are unique only in their respective enclosing
+entity. Ids are unique in the entire CloudFoundry installation. Different
+instances of the same application are separated by an integer index. Apps can
+consist of a main job and multiple tasks and side-cars, which can be
+distinguished by different process attributes.
+
+CloudFoundry can also emit signals from system components. They use a different
+approach as applications, since they are not organized into orgs and spaces.
+They align with the Bosh deployment tool of CloudFoundry.
+
+## Organization
+
+<!-- semconv cloudfoundry.org -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `cloudfoundry.org`
+
+**Description:** The organization of the application which is monitored.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cloudfoundry.org.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry org the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloudfoundry.org.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry organization the app is running in. [2] | `my-org-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.org_id`. This is the same value as
+reported by `cf org <org-name> --guid`.
+
+**[2]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.org_name`. This is the same value as
+reported by `cf orgs`.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## Space
+
+<!-- semconv cloudfoundry.space -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `cloudfoundry.space`
+
+**Description:** The space of the application which is monitored.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cloudfoundry.space.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry space the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloudfoundry.space.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry space the application is running in. [2] | `my-space-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.space_id`. This is the same value as
+reported by `cf space <space-name> --guid`.
+
+**[2]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.space_name`. This is the same value as
+reported by `cf spaces`.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## Application
+
+<!-- semconv cloudfoundry.app -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `cloudfoundry.app`
+
+**Description:** The application which is monitored.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cloudfoundry.app.id`](/docs/attributes-registry/cloudfoundry.md) | string | The guid of the application. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloudfoundry.app.name`](/docs/attributes-registry/cloudfoundry.md) | string | The name of the application. [2] | `my-app-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.application_id`. This is the same value as
+reported by `cf app <app-name> --guid`.
+
+**[2]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.application_name`. This is the same value
+as reported by `cf apps`.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## Process
+
+<!-- semconv cloudfoundry.process -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `cloudfoundry.process`
+
+**Description:** The process of the application which is monitored.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cloudfoundry.process.id`](/docs/attributes-registry/cloudfoundry.md) | string | The UID identifying the process. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloudfoundry.process.type`](/docs/attributes-registry/cloudfoundry.md) | string | The type of process. [2] | `web` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.process_id`. It is supposed to be equal to
+`VCAP_APPLICATION.app_id` for applications deployed to the runtime.
+For system components, this could be the actual PID.
+
+**[2]:** CloudFoundry applications can consist of multiple jobs. Usually the
+main process will be of type `web`. There can be additional background
+tasks or side-cars with different process types.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## Cloud Foundry System Component
+
+<!-- semconv cloudfoundry.system -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `cloudfoundry.system`
+
+**Description:** The system component which is monitored.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cloudfoundry.system.id`](/docs/attributes-registry/cloudfoundry.md) | string | A guid or another name describing the event source. [1] | `cf/gorouter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloudfoundry.system.instance.id`](/docs/attributes-registry/cloudfoundry.md) | string | A guid describing the concrete instance of the event source. [2] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** CloudFoundry defines the `source_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+It is used for logs and metrics emitted by CloudFoundry. It is
+supposed to contain the component name, e.g. "gorouter", for
+CloudFoundry components.
+
+When system components are instrumented, values from the
+[Bosh spec](https://bosh.io/docs/jobs/#properties-spec)
+should be used. The `system.id` should be set to
+`spec.deployment/spec.name`.
+
+**[2]:** CloudFoundry defines the `instance_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope).
+It is used for logs and metrics emitted by CloudFoundry. It is
+supposed to contain the vm id for CloudFoundry components.
+
+When system components are instrumented, values from the
+[Bosh spec](https://bosh.io/docs/jobs/#properties-spec)
+should be used. The `system.instance.id` should be set to `spec.id`.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md