Add CloudFoundry Resource Attributes

.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.

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)

docs/attributes-registry/cloudfoundry.md

@@ -0,0 +1,97 @@
+<!--- 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.source.type`        | string | The type of the event source. [8]                                              | `APP/PROC/WEB/0`; `APP/TASK/jobscheduler-task-70013817-ab92-4f75-82d4-de8ae4dd64b4`; `RTR`; `STG` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.space.id`           | string | The guid of the CloudFoundry space the application is running in. [9]          | `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. [10]         | `my-space-name`                                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cloudfoundry.system.id`          | string | A guid or another name describing the event source. [11]                       | `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. [12]              | `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]:** 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).
+Application developers can access the value of the `source_type` in
+the log stream generated by `cf logs <app-name>`, usually in square
+brackets.
+
+**[9]:** 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`.
+
+**[10]:** Application instrumentation should use the value from environment
+variable `VCAP_APPLICATION.space_name`. This is the same value as
+reported by `cf spaces`.
+
+**[11]:** 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`.
+
+**[12]:** 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`.

docs/resource/README.md

@@ -288,6 +288,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