Fix/skruk/documentation 093 (#60)

* fixing smaller issues in documentation
* Update documentation to include Dynatrace Subscription compatibility details
* Update documentation and comments for BizEvents, DavisEvents, and GenericEvents classes to reflect API changes and clarify usage

Author: sebastiankruk

.gitignore

@@ -26,3 +26,4 @@ LICENSE.md
 test/conf/*config-download.yml
 dynatrace-snowflake-observability-agent
 *.pkg
+.github/context/*

docs/ARCHITECTURE.md

@@ -36,6 +36,7 @@ The main capabilities offered by DSOA are:
   - [Sending metrics](#sending-metrics)
   - [Sending events](#sending-events)
   - [Sending BizEvents](#sending-bizevents)
+  - [Dynatrace Subscription Compatibility](#dynatrace-subscription-compatibility)
 - [Sending custom telemetry](#sending-custom-telemetry)
   - [Default data structure](#default-data-structure)
   - [Examples of sending custom telemetry](#examples-of-sending-custom-telemetry)
@@ -206,7 +207,8 @@ DSOA offers an internal API to send telemetry as
 [OTEL logs](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/opentelemetry/post-logs),
 [OTEL spans](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/opentelemetry/post-traces),
 [metrics](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/metric-v2),
-[events](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/events-v2), and
+[generic events](https://docs.dynatrace.com/docs/platform/openpipeline/reference/openpipeline-ingest-api/generic-events/events-generic-builtin), and
+[Davis events](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/events-v2), and
 [BizEvents](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/business-analytics-v2).
 
 ### Sending logs
@@ -225,15 +227,11 @@ traces/spans.
 
 Traces/spans delivery can be adjusted in the configuration:
 
-```json
-{
-  "OTEL": {
-    "SPANS": {
-      "EXPORT_TIMEOUT_MILLIS": 10000,
-      "MAX_EXPORT_BATCH_SIZE": 50
-    }
-  }
-}
+```yaml
+otel:
+  spans:
+    export_timeout_millis: 10000
+    max_export_batch_size: 50
 ```
 
 ### Sending metrics
@@ -247,35 +245,29 @@ avoid creating redundant calls.
 The internal telemetry API enables for metrics cache to be manually flushed before reaching the maximum payload. The maximum size of payload
 and maximum number of retries to send data can be configured:
 
-```json
-{
-  "OTEL": {
-    "METRICS": {
-      "MAX_RETRIES": 5,
-      "MAX_BATCH_SIZE": 1000000
-    }
-  }
-}
+```yaml
+otel:
+  metrics:
+    max_retries: 5
+    max_batch_size: 1000000
 ```
 
 ### Sending events
 
 Dynatrace Snowflake Observability Agent enables to send events using the
-[Dynatrace Events API v2](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/events-v2).
+[Dynatrace OpenPipeline Events API](https://docs.dynatrace.com/docs/platform/openpipeline/reference/openpipeline-ingest-api/generic-events/events-generic-builtin) (`/platform/ingest/v1/events`).
+
+> **Note:** The OpenPipeline Events API requires a [Dynatrace Platform Subscription (DPS)](https://www.dynatrace.com/pricing/dynatrace-platform-subscription/). Tenants without DPS cannot receive events sent through this endpoint. See [Dynatrace Subscription Compatibility](#dynatrace-subscription-compatibility) for guidance on configuring DSOA for non-DPS tenants.
 
 Each event has columns specifying the event type and title accompanied by additional attributes describing its details. Dynatrace API for
 Events require each event to be send separately. Dynatrace Snowflake Observability Agent enables to configure maximum number of retries and
 delay (in milliseconds) between retries, in case event could not be delivered.
 
-```json
-{
-  "OTEL": {
-    "EVENTS": {
-      "MAX_RETRIES": 5,
-      "RETRY_DELAY": 10000
-    }
-  }
-}
+```yaml
+otel:
+  events:
+    max_retries: 5
+    retry_delay_ms: 10000
 ```
 
 ### Sending BizEvents
@@ -284,26 +276,42 @@ Dynatrace Snowflake Observability Agent is also capable of sending special type
 using the
 [Dynatrace Business Events API v2](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/business-analytics-v2).
 
+> **Note:** BizEvents are stored in Grail (Dynatrace's data lakehouse) and therefore require a [Dynatrace Platform Subscription (DPS)](https://www.dynatrace.com/pricing/dynatrace-platform-subscription/). Tenants without DPS cannot receive BizEvents. See [Dynatrace Subscription Compatibility](#dynatrace-subscription-compatibility) for guidance on configuring DSOA for non-DPS tenants.
+
 Those events are usually used for tracking execution of actions within Dynatrace Snowflake Observability Agent flow. Each posted business
 event is required to have fields specifying its `id`, `source`, `specversion`, and `type`. Dynatrace Snowflake Observability Agent sends
 business events as batch of `CloudEvent` objects.
 
 There are multiple parameters of delivering BizEvents can be configured:
 
-```json
-{
-    "OTEL": {
-        "BIZ_EVENTS": {
-            "MAX_RETRIES": 5,
-            "MAX_PAYLOAD_BYTES": 1000 * 1024 * 5,
-            "MAX_EVENT_COUNT": 400,
-            "RETRY_DELAY_MS": 10000,
-            "RETRY_ON_STATUS": [429, 502, 503]
-        }
-    }
-}
+```yaml
+otel:
+  biz_events:
+    max_retries: 5
+    max_payload_bytes: 5120000  # 1000 * 1024 * 5
+    max_event_count: 400
+    retry_delay_ms: 10000
+    retry_on_status: [429, 502, 503]
 ```
 
+### Dynatrace Subscription Compatibility
+
+Not all DSOA telemetry types are available on every Dynatrace deployment. Some signal types depend on
+[Dynatrace Platform Subscription (DPS)](https://www.dynatrace.com/pricing/dynatrace-platform-subscription/), which provides access to
+Grail (Dynatrace's data lakehouse) and the OpenPipeline ingestion APIs.
+
+| Signal Type        | Endpoint                     | DPS Required | Notes                                           |
+| ------------------ | ---------------------------- | ------------ | ----------------------------------------------- |
+| **Logs**           | `/api/v2/otlp/v1/logs`       | No           | Available on all tenants                        |
+| **Metrics**        | `/api/v2/metrics/ingest`     | No           | Available on all tenants                        |
+| **Spans**          | `/api/v2/otlp/v1/traces`     | No           | Available on all tenants                        |
+| **Davis Events**   | `/api/v2/events/ingest`      | No           | Classic Events API v2, available on all tenants |
+| **BizEvents**      | `/api/v2/bizevents/ingest`   | **Yes**      | Stored in Grail; requires DPS                   |
+| **Generic Events** | `/platform/ingest/v1/events` | **Yes**      | OpenPipeline-only; requires DPS                 |
+
+For guidance on configuring DSOA for a non-DPS Dynatrace tenant, see
+[Using DSOA Without a Dynatrace Platform Subscription](INSTALL.md#using-dsoa-without-a-dynatrace-platform-subscription) in INSTALL.md.
+
 ## Sending custom telemetry
 
 Apart from sending telemetry prepared by plugins, Dynatrace Snowflake Observability Agent enables sending custom telemetry using the
@@ -401,7 +409,7 @@ call APP.SEND_TELEMETRY(ARRAY_CONSTRUCT(
             'value.str', 'test',
             'value.bool', true,
             'value.list', ARRAY_CONSTRUCT(1, '2', 3),
-            'value.dict', OBJECT CONSTRUCT('k', 'v', 'k2', 2)
+            'value.dict', OBJECT_CONSTRUCT('k', 'v', 'k2', 2)
         ),
         OBJECT_CONSTRUCT(
             'timestamp', 1732103723000,
@@ -411,8 +419,8 @@ call APP.SEND_TELEMETRY(ARRAY_CONSTRUCT(
             'value.int', 10000000,
             'value.str', 'test 2',
             'value.bool', false,
-            'value.list', ARRAY CONSTRUCT('1', '2'),
-            'value.dict', OBJECT CONSTRUCT('k', 1, 'k2', 2)
+            'value.list', ARRAY_CONSTRUCT('1', '2'),
+            'value.dict', OBJECT_CONSTRUCT('k', 1, 'k2', 2)
         ),
         OBJECT_CONSTRUCT(
             'timestamp', 1732103723000,
@@ -432,15 +440,11 @@ call APP.SEND_TELEMETRY(ARRAY_CONSTRUCT(
 
 Dynatrace Snowflake Observability Agent has configurable self-monitoring capabilities.
 
-```json
-{
-  "PLUGINS": {
-    "SELF_MONITORING": {
-      "SEND_BIZEVENTS_ON_DEPLOY": true,
-      "SEND_BIZEVENTS_ON_RUN": true
-    }
-  }
-}
+```yaml
+plugins:
+  self_monitoring:
+    send_bizevents_on_deploy: true
+    send_bizevents_on_run: true
 ```
 
 With `SEND_BIZEVENTS_ON_RUN` set to `true` Dynatrace Snowflake Observability Agent will provide updates to DT on the statuses of executed

docs/INSTALL.md

@@ -439,7 +439,7 @@ This approach provides a structured way to have a Snowflake administrator initia
 
     ```bash
     export HISTCONTROL=ignorespace
-    export DTAGENT_TOKEN="your-dynatrace-token"
+     export DTAGENT_TOKEN="your-dynatrace-token"
 
     # If you included admin setup (or do not want to install use the admin role) in your custom init script:
     ./deploy.sh custom-init --scope=setup,plugins,config,agents,apikey
@@ -821,6 +821,31 @@ The `otel` section allows you to configure OpenTelemetry behavior. By default, y
 | `biz_events.retry_on_status`           | Array[Integer] | -       | HTTP status codes that trigger retry                                       |
 | `biz_events.is_disabled`               | Boolean        | `false` | Disable business events telemetry export                                   |
 
+#### Using DSOA Without a Dynatrace Platform Subscription
+
+Some DSOA telemetry types require a [Dynatrace Platform Subscription (DPS)](https://www.dynatrace.com/pricing/dynatrace-platform-subscription/)
+because they rely on Grail or OpenPipeline ingestion APIs that are only available with DPS:
+
+- **Generic (OpenPipeline) Events** (`otel.events`) — require DPS
+- **BizEvents** (`otel.biz_events`) — require DPS (stored in Grail)
+
+**Logs, metrics, spans, and Davis Events work on all Dynatrace tenants**, regardless of subscription tier.
+
+If your Dynatrace tenant does not have a DPS subscription, add the following to your profile configuration to disable the
+non-compatible signal types:
+
+```yaml
+otel:
+  events:
+    is_disabled: true
+  biz_events:
+    is_disabled: true
+```
+
+With this configuration, DSOA delivers full observability coverage through logs, metrics, and spans. Self-monitoring BizEvents
+and plugin event alerts will be silently suppressed rather than causing errors. See [ARCHITECTURE.md](ARCHITECTURE.md#dynatrace-subscription-compatibility)
+for the full signal compatibility table.
+
 #### Plugin Scheduling
 
 One of the configuration options for each Dynatrace Snowflake Observability Agent plugin is the `schedule`, which determines when the

src/dtagent/otel/events/bizevents.py

@@ -45,7 +45,11 @@
 
 
 class BizEvents(AbstractEvents):
-    """Class parsing and sending bizevents."""
+    """Class parsing and sending bizevents via BizEvents API
+    https://docs.dynatrace.com/docs/observe/business-observability/bo-api-ingest
+
+    NOTE: BizEvents are delivered to Dynatrace using CloudEvents batch format.
+    """
 
     from dtagent.config import Configuration  # COMPILE_REMOVE
 

src/dtagent/otel/events/davis.py

@@ -50,7 +50,7 @@
 
 class DavisEvents(GenericEvents):
     """Allows for parsing and sending (Davis) Events payloads via Events v2 API
-    https://docs.dynatrace.com/docs/discover-dynatrace/platform/openpipeline/reference/api-ingestion-reference#davis-events
+    https://docs.dynatrace.com/docs/dynatrace-api/environment-api/events-v2/post-event
 
     Note: Events API does not support sending multiple events at the same time, as a bulk, like in BizEvents or OpenPipelineEvents.
 

src/dtagent/otel/events/generic.py

@@ -51,7 +51,7 @@
 
 class GenericEvents(AbstractEvents):
     """Enables for parsing and sending Events via OpenPipeline Events API
-    https://docs.dynatrace.com/docs/discover-dynatrace/platform/openpipeline/reference/api-ingestion-reference
+    https://docs.dynatrace.com/docs/platform/openpipeline/reference/openpipeline-ingest-api/generic-events/events-generic-builtin
 
     Note: OpenPipeline Events API does support sending multiple events at the same time, similar to BizEvents.
     """