# 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 resource.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] `cloudfoundry.org.id`:** 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] `cloudfoundry.org.name`:** 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 resource.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] `cloudfoundry.space.id`:** 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] `cloudfoundry.space.name`:** 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 resource.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] `cloudfoundry.app.id`:** 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.app.name`:** 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 resource.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] `cloudfoundry.process.id`:** 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.process.type`:** 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 resource.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.system.id`:** 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`.

**[2] `cloudfoundry.system.instance.id`:** 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`.

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

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