Skip to content

Commit

Permalink
Add CloudFoundry resource attributes
Browse files Browse the repository at this point in the history 
Using the CloudFoundry documentation, provides a set of
resource attribute describing CloudFoundry workloads. Both
applications as well as system components are addressed.
Helpful resources:

* https://github.com/cloudfoundry/loggregator-api#v2-envelope
* https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION
* https://bosh.io/docs/jobs/#properties-spec
* https://docs.cloudfoundry.org/devguide/deploy-apps/streaming-logs.html

Signed-off-by: Karsten Schnitter <[email protected]>
  • Loading branch information
@KarstenSchnitter
KarstenSchnitter committed Jan 11, 2024
1 parent de9ef07 commit 9fb2ddc
Show file tree
Hide file tree
Showing 6 changed files with 444 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/attributes-registry/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Currently, the following namespaces exist:
* [Browser](browser.md)
* [Client](client.md)
* [Cloud](cloud.md)
* [CloudFoundry](cloudfoundry.md)
* [Code](code.md)
* [Container](container.md)
* [DB](db.md) (database)
Expand Down
90 changes: 90 additions & 0 deletions docs/attributes-registry/cloudfoundry.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: CloudFoundry
--->

# CloudFoundry

## CloudFoundry Resource Attributes

<!-- semconv registry.cloudfoundry(omit_requirement_level) -->
| 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 <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`.

**[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 <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]:** 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 <app-name> --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 <space-name> --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`.
<!-- endsemconv -->
1 change: 1 addition & 0 deletions docs/resource/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
167 changes: 167 additions & 0 deletions docs/resource/cloudfoundry.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
# 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

**type:** `cloudfoundry.org`

**Description:** A CloudFoundry Organization

<!-- semconv cloudfoundry.org -->
| 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 <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`.
<!-- endsemconv -->

## Space

**type:** `cloudfoundry.space`

**Description:** A CloudFoundry Space

<!-- semconv 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 <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`.
<!-- endsemconv -->

## Application

***type:** `cloudfoundry.app`

**Description:** A CloudFoundry Application

<!-- semconv cloudfoundry.app -->
| 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 <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`.
<!-- endsemconv -->

## Process

**type:** `cloudfoundry.process`

**Description:** A CloudFoundry Application Process

<!-- semconv cloudfoundry.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.
<!-- endsemconv -->

## Generic Source

**type:** `cloudfoundry`

**Description:** The generic source (app or system component)

<!-- semconv cloudfoundry(tag=generic) -->
| 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 <app-name> --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`.
<!-- endsemconv -->

## Source Type

**type:**`cloudfoundry.source_type`

**Description:** The CloudFoundry source type.

<!-- semconv cloudfoundry(tag=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).
<!-- endsemconv -->

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
Loading

0 comments on commit 9fb2ddc

Please sign in to comment.