#9: Add configuration option to disable tracking

.gitattributes

@@ -12,5 +12,5 @@ doc/changes/changelog.md                   linguist-generated=true
 .settings/org.eclipse.jdt.core.prefs       linguist-generated=true
 .settings/org.eclipse.jdt.ui.prefs         linguist-generated=true
 
-specs/_plans/                              linguist-generated=true
-specs/_recorded                            linguist-generated=true
+specs/_plans/**                            linguist-generated=true
+specs/_recorded/**                         linguist-generated=true

AGENTS.md

@@ -5,19 +5,26 @@
 - The project uses the `speq` skill, see https://github.com/marconae/speq-skill
 - The project uses OpenFastTrace (OFT).
   - Reference skill: https://github.com/itsallcode/openfasttrace/blob/main/skills/openfasttrace-skill/SKILL.md
+- The project uses [project-keeper](https://github.com/exasol/project-keeper) for managing project structure
 
-## OpenFastTrace Artifact Types
+## OpenFastTrace
+
+### OpenFastTrace Artifact Types
 
 - `feat`: high level features in the mission
 - `req`: requirements in the speq spec files
 - `impl`: implementation in code
 - `utest`: unit tests
 - `itest`: integration tests
 
-## Tag Maintenance
+### Tag Maintenance
 
 - Always add or update OpenFastTrace tags for features, requirements, and code tags when updating the mission or speq spec files.
 
-## Validation
+### Validation
 
 - Ensure that all requirements are covered by running `mvn generate-sources org.itsallcode:openfasttrace-maven-plugin:trace`.
+
+## Project Keeper
+
+If `mvn verify` fails with project keeper errors, run `mvn project-keeper:fix` and try again.

README.md

@@ -32,7 +32,7 @@ The project uses `speq` skills and recorded specs to drive planning, implementat
 - Protocol-compatible message format with `category`, protocol `version`, `productVersion`, `timestamp`, and `features`
 - Exponential backoff with retry timeout
 - Clean shutdown via `AutoCloseable`
-- Environment-variable control for disabling telemetry and overriding the endpoint
+- Host-configuration and environment-variable control for disabling telemetry, plus environment-variable endpoint override
 - Lifecycle log messages for enabled, disabled, sent-count, and stopped telemetry states
 - Zero runtime dependencies
 
@@ -57,6 +57,8 @@ try (TelemetryClient client = TelemetryClient.create(config)) {
 
 The default endpoint is `https://metrics.exasol.com`.
 
+Applications can also disable telemetry explicitly in code with `TelemetryConfig.builder(...).disableTracking()`.
+
 ## Documentation
 
 * [Developer Guide](doc/developer-guide.md)

doc/app-user-guide.md

@@ -34,6 +34,7 @@ For Exasol's general privacy information, see the [Exasol Privacy Policy](https:
 Applications can use lifecycle log messages from the library to indicate whether telemetry is enabled or disabled.
 
 When telemetry is disabled, the library does not queue or send usage events.
+Applications may disable telemetry through their own configuration and report that state in logs as `Telemetry is disabled via host configuration.`.
 
 ## How To Disable Telemetry
 

doc/changes/changes_0.2.0.md

@@ -1,10 +1,11 @@
-# Telemetry Java 0.2.0, released 2026-??-??
+# Telemetry Java 0.2.0, released 2026-04-??
 
-Code name:
+Code name: Explicitly Disable Tracking
 
 ## Summary
 
-## Features
+The new release lets host applications disable telemetry directly in code.
 
-* ISSUE_NUMBER: description
+## Features
 
+* #9: Add explicit host-controlled telemetry disablement via `TelemetryConfig.Builder.disableTracking()`

doc/integration-guide.md

@@ -17,6 +17,7 @@ try (TelemetryClient client = TelemetryClient.create(config)) {
 
 - A project short tag and a product/library version at startup. The library adds the project tag as the telemetry category and includes the configured productVersion in every accepted telemetry event.
 - An optional HTTP endpoint for JSON `POST` delivery. If omitted, the default endpoint is `https://metrics.exasol.com`.
+- An optional host-controlled disable switch via `TelemetryConfig.Builder.disableTracking()` when the integrating application exposes its own telemetry setting.
 
 ## Required Documentation
 
@@ -52,6 +53,18 @@ For details on what is collected and how to disable telemetry, see the [document
 - `CI`
   Disables telemetry automatically when set to any non-empty value.
 
+## Host-Controlled Disablement
+
+If the integrating application already has its own telemetry switch, map that setting to `TelemetryConfig.Builder.disableTracking()`.
+
+```java
+TelemetryConfig config = TelemetryConfig.builder("MyApp", "1.2.3")
+        .disableTracking()
+        .build();
+```
+
+When telemetry is disabled this way, the lifecycle `INFO` log reports `Telemetry is disabled via host configuration.`.
+
 ### UDF Integration Tests
 
 For Exasol UDF integration tests, disable telemetry explicitly so test executions never emit usage data. In UDF script definitions, set `%env EXASOL_TELEMETRY_DISABLE=1;`.

specs/config/tracking-controls/spec.md

@@ -32,6 +32,13 @@ Tracking can be deactivated by `EXASOL_TELEMETRY_DISABLE` or automatically by `C
 * *THEN* the library SHALL disable telemetry collection and delivery
 * *AND* the library MUST NOT enqueue or send usage events while disabled
 
+### Scenario: Disables tracking via explicit host configuration
+
+* *GIVEN* the host application configures telemetry as disabled in code
+* *WHEN* the host application initializes the library and records feature usage
+* *THEN* the library SHALL disable telemetry collection and delivery
+* *AND* the library MUST NOT enqueue or send usage events while disabled
+
 ### Scenario: Overrides the configured endpoint via environment variable
 
 * *GIVEN* the host application configures an endpoint, project tag, and `productVersion` in code

specs/lifecycle/status-logging/spec.md

@@ -31,8 +31,8 @@ These log messages are informational lifecycle messages only. They do not includ
 * *GIVEN* the telemetry client is created and telemetry is disabled
 * *WHEN* initialization completes
 * *THEN* the library SHALL log at `INFO` level that telemetry is disabled
-* *AND* the library SHALL identify whether telemetry was disabled by `EXASOL_TELEMETRY_DISABLE` or `CI`
-* *AND* the library SHALL include the actual env-var value that caused disablement
+* *AND* the library SHALL identify whether telemetry was disabled by host configuration, `EXASOL_TELEMETRY_DISABLE`, or `CI`
+* *AND* the library SHALL include the actual env-var value that caused disablement when disablement came from `EXASOL_TELEMETRY_DISABLE` or `CI`
 
 ### Scenario: Logs message counts when telemetry is sent