Rename CF generic attributes

* source_id -> source.id * instance_id -> instance.id * source_type -> source.type Add clarification on source_type: * required if log message * comment on obtaining the value Signed-off-by: Karsten Schnitter <k.schnitter@sap.com>
open-telemetry · Jan 15, 2024 · f4efa59 · f4efa59
1 parent 7a9b0b4
commit f4efa59
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 22 deletions.
diff --git a/docs/attributes-registry/cloudfoundry.md b/docs/attributes-registry/cloudfoundry.md
@@ -11,13 +11,13 @@ linkTitle: CloudFoundry
 |---|---|---|---|
 | `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.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.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` |
 
@@ -38,7 +38,7 @@ 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`.
+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
@@ -68,7 +68,7 @@ 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
+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
@@ -79,6 +79,9 @@ 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.
 
 **[10]:** Application instrumentation should use the value from environment
 variable `VCAP_APPLICATION.space_id`. This is the same value as

diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md
@@ -114,8 +114,8 @@ tasks or side-cars with different process types.
 <!-- 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 |
+| [`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
@@ -126,7 +126,7 @@ 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`.
+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
@@ -139,20 +139,20 @@ 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
+should be used. The `source.id` should be set to
 `spec.deployment/spec.name`.
 <!-- endsemconv -->
 
 ## Source Type
 
-**type:**`cloudfoundry.source_type`
+**type:**`cloudfoundry.source.type`
 
 **Description:** The CloudFoundry source type.
 
-<!-- semconv cloudfoundry(tag=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 |
+| [`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` | Conditionally Required: if the the event is a log message |
 
 **[1]:** CloudFoundry generates log messages with different source types for an
 applications. This indicates, whether the log was created from the
@@ -162,6 +162,9 @@ 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.
 <!-- endsemconv -->
 
 [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
@@ -5,7 +5,7 @@ groups:
     brief: >
       CloudFoundry resource attributes.
     attributes:
-      - id: source_id
+      - id: source.id
         type: string
         brief: >
           A guid or another name describing the event source.
@@ -21,12 +21,12 @@ groups:
           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
+          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
+      - id: instance.id
         type: string
         brief: >
           An index or guid describing the concrete instance of the event source.
@@ -40,7 +40,7 @@ groups:
           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`.
+          should be used. The `instance.id` should be set to `spec.id`.
         examples:
           - '0'
           - '218fc5a9-a5f1-4b54-aa05-46717d0ab26d'
@@ -98,7 +98,7 @@ groups:
           variable `VCAP_APPLICATION.org_id`. This is the same value as
           reported by `cf org <org-name> --guid`.
         examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d']
-      - id: source_type
+      - id: source.type
         type: string
         brief: >
           The type of the event source.
@@ -111,6 +111,9 @@ groups:
           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.
         examples:
           - 'APP/PROC/WEB/0'
           - 'APP/TASK/jobscheduler-task-70013817-ab92-4f75-82d4-de8ae4dd64b4'

diff --git a/model/resource/cloudfoundry.yaml b/model/resource/cloudfoundry.yaml
@@ -5,15 +5,16 @@ groups:
     brief: >
       A CloudFoundry application or sytem component.
     attributes:
-      - ref: cloudfoundry.source_id
+      - ref: cloudfoundry.source.id
         requirement_level: required
         tag: generic
-      - ref: cloudfoundry.instance_id
+      - ref: cloudfoundry.instance.id
         requirement_level: required
         tag: generic
-      - ref: cloudfoundry.source_type
-        requirement_level: recommended
-        tag: source_type
+      - ref: cloudfoundry.source.type
+        requirement_level:
+          conditionally_required: if the the event is a log message
+        tag: source.type
   - id: cloudfoundry.app
     prefix: cloudfoundry.app
     type: resource