diff --git a/.chloggen/cf-resource.yaml b/.chloggen/cf-resource.yaml new file mode 100644 index 0000000000..d30ce7052c --- /dev/null +++ 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 index d0efd84320..e4e6d6b430 100644 --- 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 index 206cc1c715..4c9316ddf1 100644 --- 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 index 1c9cfe8ef9..e6e543158e 100644 --- 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 index 3f9eba31c4..680baa7fda 100644 --- 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 index b5688cac23..35356a67cb 100644 --- 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 new file mode 100644 index 0000000000..26074805e8 --- /dev/null +++ b/docs/attributes-registry/cloudfoundry.md @@ -0,0 +1,84 @@ + + + + + +# 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 --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 --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 --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 index ca2387cb52..43b9abe51a 100644 --- 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 new file mode 100644 index 0000000000..a6cd9f241b --- /dev/null +++ b/docs/resource/cloudfoundry.md @@ -0,0 +1,219 @@ +# CloudFoundry + +**Status**: [Experimental][DocumentStatus] + +Useful resources to understand CloudFoundry metadata: + +* +* +* +* + +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 + + + + + + + + + +**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 --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`. + + + + + + + + + +## Space + + + + + + + + + +**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 --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`. + + + + + + + + + +## Application + + + + + + + + + +**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 --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`. + + + + + + + + + +## Process + + + + + + + + + +**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. + + + + + + + + + +## Cloud Foundry System Component + + + + + + + + + +**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`. + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/cloudfoundry/registry.yaml b/model/cloudfoundry/registry.yaml new file mode 100644 index 0000000000..c360d69335 --- /dev/null +++ b/model/cloudfoundry/registry.yaml @@ -0,0 +1,135 @@ +groups: + - id: registry.cloudfoundry + type: attribute_group + brief: > + CloudFoundry resource attributes. + attributes: + - id: cloudfoundry.system.id + type: string + stability: experimental + brief: > + A guid or another name describing the event source. + note: | + 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`. + examples: + - 'cf/gorouter' + - id: cloudfoundry.system.instance.id + type: string + stability: experimental + brief: > + A guid describing the concrete instance of the event source. + note: | + 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`. + examples: + - '218fc5a9-a5f1-4b54-aa05-46717d0ab26d' + - id: cloudfoundry.app.name + type: string + stability: experimental + brief: > + The name of the application. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.application_name`. This is the same value + as reported by `cf apps`. + examples: ['my-app-name'] + - id: cloudfoundry.app.id + type: string + stability: experimental + brief: > + The guid of the application. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.application_id`. This is the same value as + reported by `cf app --guid`. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: cloudfoundry.app.instance.id + type: string + stability: experimental + brief: > + The index of the application instance. 0 when just one instance is active. + note: | + 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`. + examples: + - '0' + - '1' + - id: cloudfoundry.space.name + type: string + stability: experimental + brief: > + The name of the CloudFoundry space the application is running in. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.space_name`. This is the same value as + reported by `cf spaces`. + examples: ['my-space-name'] + - id: cloudfoundry.space.id + type: string + stability: experimental + brief: > + The guid of the CloudFoundry space the application is running in. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.space_id`. This is the same value as + reported by `cf space --guid`. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: cloudfoundry.org.name + type: string + stability: experimental + brief: > + The name of the CloudFoundry organization the app is running in. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.org_name`. This is the same value as + reported by `cf orgs`. + examples: ['my-org-name'] + - id: cloudfoundry.org.id + type: string + stability: experimental + brief: > + The guid of the CloudFoundry org the application is running in. + note: | + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.org_id`. This is the same value as + reported by `cf org --guid`. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: cloudfoundry.process.id + type: string + stability: experimental + brief: > + The UID identifying the process. + note: | + 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. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: cloudfoundry.process.type + type: string + stability: experimental + brief: > + The type of process. + note: | + 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. + examples: ['web'] diff --git a/model/cloudfoundry/resources.yaml b/model/cloudfoundry/resources.yaml new file mode 100644 index 0000000000..95d60abe35 --- /dev/null +++ b/model/cloudfoundry/resources.yaml @@ -0,0 +1,41 @@ +groups: + - id: cloudfoundry.system + type: resource + name: cloudfoundry.system + brief: > + The system component which is monitored. + attributes: + - ref: cloudfoundry.system.id + - ref: cloudfoundry.system.instance.id + - id: cloudfoundry.app + type: resource + name: cloudfoundry.app + brief: > + The application which is monitored. + attributes: + - ref: cloudfoundry.app.id + - ref: cloudfoundry.app.name + - id: cloudfoundry.space + type: resource + name: cloudfoundry.space + brief: > + The space of the application which is monitored. + attributes: + - ref: cloudfoundry.space.id + - ref: cloudfoundry.space.name + - id: cloudfoundry.org + type: resource + name: cloudfoundry.org + brief: > + The organization of the application which is monitored. + attributes: + - ref: cloudfoundry.org.id + - ref: cloudfoundry.org.name + - id: cloudfoundry.process + type: resource + name: cloudfoundry.process + brief: > + The process of the application which is monitored. + attributes: + - ref: cloudfoundry.process.id + - ref: cloudfoundry.process.type diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index ef9bc5c120..104823f184 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -10,6 +10,7 @@ acronyms: - AWS - CICD - CloudEvents + - CloudFoundry - CLR - CPU - CSI