fixup docs

Contrast-Security-OSS · Nov 20, 2024 · 47aa46e · 47aa46e
1 parent 07456d7
commit 47aa46e
Show file tree

Hide file tree

Showing 6 changed files with 22 additions and 66 deletions.
diff --git a/docs/attributes-registry/contrast.md b/docs/attributes-registry/contrast.md
@@ -47,11 +47,11 @@ Describes attributes for Contrast Action span of type host-cmd-exec.
 
 contrast defined resources for observability data
 
-| Attribute                                                                                        | Type   | Description                                                            | Examples                          | Stability                                                        |
-| ------------------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------- |
-| <a id="contrast-deployment" href="#contrast-deployment">`contrast.deployment`</a>                | string | deployment environment                                                 | `QA`; `DEVELOPMENT`; `PRODUCTION` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="contrast-semconv-version" href="#contrast-semconv-version">`contrast.semconv.version`</a> | string | The version of contrast semantic conventions that the data adheres to. | `0.3.0`                           | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="otel-semconv-version" href="#otel-semconv-version">`otel.semconv.version`</a>             | string | The version of otel semantic conventions that the data adheres to.     | `1.22.0`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute                                                                                        | Type   | Description                                                       | Examples                          | Stability                                                        |
+| ------------------------------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------- |
+| <a id="contrast-deployment" href="#contrast-deployment">`contrast.deployment`</a>                | string | deployment environment                                            | `QA`; `DEVELOPMENT`; `PRODUCTION` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="contrast-semconv-version" href="#contrast-semconv-version">`contrast.semconv.version`</a> | string | The version of contrast semantic conventions the data adheres to. | `0.3.0`                           | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="otel-semconv-version" href="#otel-semconv-version">`otel.semconv.version`</a>             | string | The version of otel semantic conventions the data adheres to.     | `1.22.0`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `contrast.deployment` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

diff --git a/docs/contrast/README.md b/docs/contrast/README.md
@@ -46,9 +46,9 @@ action nor will it contain enough information to determine the action execution
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`contrast.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of contrast semantic conventions that the data adheres to. | `0.3.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`otel.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of otel semantic conventions that the data adheres to. | `1.22.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`contrast.deployment`](/docs/attributes-registry/attributes.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`contrast.deployment`](/docs/attributes-registry/contrast.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`contrast.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of contrast semantic conventions the data adheres to. | `0.3.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`otel.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of otel semantic conventions the data adheres to. | `1.22.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `contrast.deployment` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

diff --git a/docs/resource/README.md b/docs/resource/README.md
@@ -241,9 +241,9 @@ a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentatio
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`contrast.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of contrast semantic conventions that the data adheres to. | `0.3.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`otel.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of otel semantic conventions that the data adheres to. | `1.22.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`contrast.deployment`](/docs/attributes-registry/attributes.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`contrast.deployment`](/docs/attributes-registry/contrast.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`contrast.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of contrast semantic conventions the data adheres to. | `0.3.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`otel.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of otel semantic conventions the data adheres to. | `1.22.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 `contrast.deployment` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

diff --git a/docs/resource/contrast-resources.md b/docs/resource/contrast-resources.md
@@ -1,46 +1,10 @@
-# Contrast Resource additions
-
-<!-- semconv resource.contrast -->
-<!-- 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:** `contrast`
-
-**Description:** Additional attributes for Contrast Sensors to provide
-
-| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-|---|---|---|---|---|---|
-| [`contrast.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of contrast semantic conventions that the data adheres to. | `0.3.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`otel.semconv.version`](/docs/attributes-registry/attributes.md) | string | The version of otel semantic conventions that the data adheres to. | `1.22.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`contrast.deployment`](/docs/attributes-registry/attributes.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-
-`contrast.deployment` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
-
-| Value  | Description | Stability |
-|---|---|---|
-| `DEVELOPMENT` | development environment | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `PRODUCTION` | production environment | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `QA` | quality assurance environment | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-<!-- END AUTOGENERATED TEXT -->
-<!-- endsemconv -->
-
-# Full Dimensional for Agent Observations
+# Dimensions for Agent Observations
 
 To properly associate measurements to the same "dimension" so that correlation algorithms work effectively, here are a
-list of attributes which agents should produce. Attributes marked as required are necessary for some form of event 
+list of attributes which agents should produce. Attributes marked as required are necessary for some form of event
 association support on the backend. Attributes marked as recommended are **strongly encouraged** for *good* association
 support by the backend processors.
 
-
 <!-- semconv attributes.contrast.dimensional -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -50,19 +14,19 @@ support by the backend processors.
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`contrast.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of contrast semantic conventions that the data adheres to. | `0.3.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`otel.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of otel semantic conventions that the data adheres to. | `1.22.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`service.name`](/docs/attributes-registry/service.md) | string | Logical name of the service. [2] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`telemetry.sdk.language`](/docs/attributes-registry/telemetry.md) | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`telemetry.sdk.name`](/docs/attributes-registry/telemetry.md) | string | The name of the telemetry SDK as defined above. [3] | `opentelemetry`; `contrast` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`telemetry.sdk.version`](/docs/attributes-registry/telemetry.md) | string | The version string of the telemetry SDK. | `1.2.3` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [4] | `GET`; `POST`; `HEAD` | `Conditionally Required` iff event is scoped to an http request | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` iff event is scoped to an http request | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [4] | `GET`; `POST`; `HEAD` | `Conditionally Required` iff observation is scoped to an http request | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`http.route`](/docs/attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` iff observation is scoped to an http request | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`cloud.provider`](/docs/attributes-registry/cloud.md) | string | Name of the cloud provider. | `alibaba_cloud`; `aws`; `azure` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`cloud.region`](/docs/attributes-registry/cloud.md) | string | The geographical region the resource is running. [6] | `us-central1`; `us-east-1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [7] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`contrast.deployment`](/docs/attributes-registry/contrast.md) | string | deployment environment | `QA`; `DEVELOPMENT`; `PRODUCTION` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`contrast.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of contrast semantic conventions the data adheres to. | `0.3.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`otel.semconv.version`](/docs/attributes-registry/contrast.md) | string | The version of otel semantic conventions the data adheres to. | `1.22.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [8] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`service.version`](/docs/attributes-registry/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`telemetry.distro.name`](/docs/attributes-registry/telemetry.md) | string | The name of the auto instrumentation agent or distribution, if used. [9] | `contrast-java` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

diff --git a/model/contrast/registry.yaml b/model/contrast/registry.yaml
@@ -4,17 +4,15 @@ groups:
     brief: "contrast defined resources for observability data"
     attributes:
       - id: contrast.semconv.version
-        brief: The version of contrast semantic conventions that the data adheres to.
+        brief: The version of contrast semantic conventions the data adheres to.
         type: string
         stability: experimental
-        requirement_level: required
         examples:
           - "0.3.0"
       - id: otel.semconv.version
-        brief: The version of otel semantic conventions that the data adheres to.
+        brief: The version of otel semantic conventions the data adheres to.
         type: string
         stability: experimental
-        requirement_level: required
         examples:
           - "1.22.0"
       - id: contrast.deployment
@@ -306,10 +304,10 @@ groups:
     attributes:
       - ref: http.route
         requirement_level:
-          conditionally_required: iff event is scoped to an http request
+          conditionally_required: iff observation is scoped to an http request
       - ref: http.request.method
         requirement_level:
-          conditionally_required: iff event is scoped to an http request
+          conditionally_required: iff observation is scoped to an http request
       - ref: service.namespace
       - ref: service.name
         requirement_level: required

diff --git a/model/contrast/resources.yaml b/model/contrast/resources.yaml
@@ -4,10 +4,4 @@ groups:
     type: resource
     brief: >
       Additional attributes for Contrast Sensors to provide
-    attributes:
-      - ref: contrast.semconv.version
-        requirement_level: required
-      - ref: otel.semconv.version
-        requirement_level: required
-      - ref: contrast.deployment
-        requirement_level: recommended
+    extends: registry.contrast.resource