diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 89818c8380..7e6a76f173 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -29,6 +29,7 @@ Currently, the following namespaces exist: * [Client](client.md) * [Cloud](cloud.md) +* [CloudFoundry](cloudfoundry.md) * [Code](code.md) * [Container](container.md) * [DB](db.md) (database) diff --git a/docs/attributes-registry/cloudfoundry.md b/docs/attributes-registry/cloudfoundry.md new file mode 100644 index 0000000000..2c524d00d7 --- /dev/null +++ b/docs/attributes-registry/cloudfoundry.md @@ -0,0 +1,90 @@ + + +# CloudFoundry + +## CloudFoundry Resource Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `cloudfoundry.app.id` | string | The guid of the application. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | +| `cloudfoundry.app.name` | string | The name of the application. [2] | `my-app-name` | +| `cloudfoundry.instance_id` | string | An index or guid describing the concrete instance of the event source. [3] | `0`; `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | +| `cloudfoundry.org.id` | string | The guid of the CloudFoundry org the application is running in. [4] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | +| `cloudfoundry.org.name` | string | The name of the CloudFoundry organization the app is running in. [5] | `my-org-name` | +| `cloudfoundry.process.id` | string | The UID identifying the process. [6] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | +| `cloudfoundry.process.type` | string | The type of process. [7] | `web` | +| `cloudfoundry.source_id` | string | A guid or another name describing the event source. [8] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d`; `cf/gorouter` | +| `cloudfoundry.source_type` | string | The type of the event source. [9] | `APP/PROC/WEB/0`; `APP/TASK/jobscheduler-task-70013817-ab92-4f75-82d4-de8ae4dd64b4`; `RTR`; `STG` | +| `cloudfoundry.space.id` | string | The guid of the CloudFoundry space the application is running in. [10] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | +| `cloudfoundry.space.name` | string | The name of the CloudFoundry space the application is running in. [11] | `my-space-name` | + +**[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`. + +**[3]:** 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 or the vm id for CloudFoundry components. + +Application instrumentation should use the value from environment +variable `CF_INSTANCE_INDEX`. + +When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) +should be used. The `instance_id` should be set to `spec.id`. + +**[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]:** 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 application id for applications deployed on +the runtime or the component name, e.g. "gorouter", for CloudFoundry +components. + +Application instrumentation should use the value from environment +variable `VCAP_APPLICATION.application_id`. This is the same value as +reported by `cf app --guid`. + +When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) +should be used. The `source_id` should be set to +`spec.deployment/spec.name`. + +**[9]:** CloudFoundry generates log messages with different source types for an +applications. This indicates, whether the log was created from the +actual application, a background task, the central load balancer, or +the CloudFoundry runtime, e.g. during a deployment. + +The `source_type` is contained as a tag of the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). +It is also available in the syslog drain structured data as documented +in the [CloudFoundry Dev Guide](https://docs.cloudfoundry.org/devguide/deploy-apps/streaming-logs.html). + +**[10]:** Application instrumentation should use the value from environment +variable `VCAP_APPLICATION.space_id`. This is the same value as +reported by `cf space --guid`. + +**[11]:** Application instrumentation should use the value from environment +variable `VCAP_APPLICATION.space_name`. This is the same value as +reported by `cf spaces`. + \ No newline at end of file diff --git a/docs/resource/README.md b/docs/resource/README.md index 5a12b18593..30151931e4 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -210,6 +210,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..f4ea14ad40 --- /dev/null +++ b/docs/resource/cloudfoundry.md @@ -0,0 +1,167 @@ +# 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 + +**type:** `cloudfoundry.org` + +**Description:** A CloudFoundry Organization + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.org.id`](../attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry org the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | +| [`cloudfoundry.org.name`](../attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry organization the app is running in. [2] | `my-org-name` | Recommended | + +**[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 + +**type:** `cloudfoundry.space` + +**Description:** A CloudFoundry Space + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.space.id`](../attributes-registry/cloudfoundry.md) | string | The guid of the CloudFoundry space the application is running in. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | +| [`cloudfoundry.space.name`](../attributes-registry/cloudfoundry.md) | string | The name of the CloudFoundry space the application is running in. [2] | `my-space-name` | Recommended | + +**[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 + +***type:** `cloudfoundry.app` + +**Description:** A CloudFoundry Application + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.app.id`](../attributes-registry/cloudfoundry.md) | string | The guid of the application. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | +| [`cloudfoundry.app.name`](../attributes-registry/cloudfoundry.md) | string | The name of the application. [2] | `my-app-name` | Recommended | + +**[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 + +**type:** `cloudfoundry.process` + +**Description:** A CloudFoundry Application Process + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.process.id`](../attributes-registry/cloudfoundry.md) | string | The UID identifying the process. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | +| [`cloudfoundry.process.type`](../attributes-registry/cloudfoundry.md) | string | The type of process. [2] | `web` | Recommended | + +**[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. + + +## Generic Source + +**type:** `cloudfoundry` + +**Description:** The generic source (app or system component) + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.instance_id`](../attributes-registry/cloudfoundry.md) | string | An index or guid describing the concrete instance of the event source. [1] | `0`; `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Required | +| [`cloudfoundry.source_id`](../attributes-registry/cloudfoundry.md) | string | A guid or another name describing the event source. [2] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d`; `cf/gorouter` | Required | + +**[1]:** 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 or the vm id for CloudFoundry components. + +Application instrumentation should use the value from environment +variable `CF_INSTANCE_INDEX`. + +When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) +should be used. The `instance_id` should be set to `spec.id`. + +**[2]:** 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 application id for applications deployed on +the runtime or the component name, e.g. "gorouter", for CloudFoundry +components. + +Application instrumentation should use the value from environment +variable `VCAP_APPLICATION.application_id`. This is the same value as +reported by `cf app --guid`. + +When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) +should be used. The `source_id` should be set to +`spec.deployment/spec.name`. + + +## Source Type + +**type:**`cloudfoundry.source_type` + +**Description:** The CloudFoundry source type. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`cloudfoundry.source_type`](../attributes-registry/cloudfoundry.md) | string | The type of the event source. [1] | `APP/PROC/WEB/0`; `APP/TASK/jobscheduler-task-70013817-ab92-4f75-82d4-de8ae4dd64b4`; `RTR`; `STG` | Recommended | + +**[1]:** CloudFoundry generates log messages with different source types for an +applications. This indicates, whether the log was created from the +actual application, a background task, the central load balancer, or +the CloudFoundry runtime, e.g. during a deployment. + +The `source_type` is contained as a tag of the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). +It is also available in the syslog drain structured data as documented +in the [CloudFoundry Dev Guide](https://docs.cloudfoundry.org/devguide/deploy-apps/streaming-logs.html). + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/registry/cloudfoundry.yaml b/model/registry/cloudfoundry.yaml new file mode 100644 index 0000000000..b921648add --- /dev/null +++ b/model/registry/cloudfoundry.yaml @@ -0,0 +1,137 @@ +groups: + - id: registry.cloudfoundry + prefix: cloudfoundry + type: resource + brief: > + CloudFoundry resource attributes. + attributes: + - id: source_id + type: string + brief: > + A guid or another name describing the event source. + note: | + 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 application id for applications deployed on + the runtime or the component name, e.g. "gorouter", for CloudFoundry + components. + + Application instrumentation should use the value from environment + variable `VCAP_APPLICATION.application_id`. This is the same value as + reported by `cf app --guid`. + + When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) + should be used. The `source_id` should be set to + `spec.deployment/spec.name`. + examples: + - '218fc5a9-a5f1-4b54-aa05-46717d0ab26d' + - 'cf/gorouter' + - id: instance_id + type: string + brief: > + An index or guid describing the concrete instance of the event source. + 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 or the vm id for CloudFoundry components. + + Application instrumentation should use the value from environment + variable `CF_INSTANCE_INDEX`. + + When system components are instrumented, values from the [Bosh spec](https://bosh.io/docs/jobs/#properties-spec) + should be used. The `instance_id` should be set to `spec.id`. + examples: + - '0' + - '218fc5a9-a5f1-4b54-aa05-46717d0ab26d' + - id: app.name + type: string + 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: app.id + type: string + 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: space.name + type: string + 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: space.id + type: string + 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: org.name + type: string + 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: org.id + type: string + 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: source_type + type: string + brief: > + The type of the event source. + note: | + CloudFoundry generates log messages with different source types for an + applications. This indicates, whether the log was created from the + actual application, a background task, the central load balancer, or + the CloudFoundry runtime, e.g. during a deployment. + + The `source_type` is contained as a tag of the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). + It is also available in the syslog drain structured data as documented + in the [CloudFoundry Dev Guide](https://docs.cloudfoundry.org/devguide/deploy-apps/streaming-logs.html). + examples: + - 'APP/PROC/WEB/0' + - 'APP/TASK/jobscheduler-task-70013817-ab92-4f75-82d4-de8ae4dd64b4' + - 'RTR' + - 'STG' + - id: process.id + type: string + 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: process.type + type: string + 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/resource/cloudfoundry.yaml b/model/resource/cloudfoundry.yaml new file mode 100644 index 0000000000..412cdc9ad7 --- /dev/null +++ b/model/resource/cloudfoundry.yaml @@ -0,0 +1,48 @@ +groups: + - id: cloudfoundry + prefix: cloudfoundry + type: resource + brief: > + A CloudFoundry application or sytem component. + attributes: + - ref: cloudfoundry.source_id + requirement_level: required + tag: generic + - ref: cloudfoundry.instance_id + requirement_level: required + tag: generic + - ref: cloudfoundry.source_type + requirement_level: recommended + tag: source_type + - id: cloudfoundry.app + prefix: cloudfoundry.app + type: resource + brief: > + The application which is monitored. + attributes: + - ref: cloudfoundry.app.id + - ref: cloudfoundry.app.name + - id: cloudfoundry.space + prefix: cloudfoundry.space + type: resource + brief: > + The space of the application which is monitored. + attributes: + - ref: cloudfoundry.space.id + - ref: cloudfoundry.space.name + - id: cloudfoundry.org + prefix: cloudfoundry.org + type: resource + brief: > + The organization of the application which is monitored. + attributes: + - ref: cloudfoundry.org.id + - ref: cloudfoundry.org.name + - id: cloudfoundry.process + prefix: cloudfoundry.process + type: resource + brief: > + The process of the application which is monitored. + attributes: + - ref: cloudfoundry.process.id + - ref: cloudfoundry.process.type