add Auth and metrics findings (#88)

* add Auth and metrics findings

Signed-off-by: MJarmo <michal.jarmolkiewicz@sap.com>

* cloned by test script

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

* code:format

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

* revert

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

* task code:format

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

* add section for mTLS

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

---------

Signed-off-by: MJarmo <michal.jarmolkiewicz@sap.com>
Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>
Co-authored-by: MJarmo <michal.jarmolkiewicz@sap.com>
Co-authored-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

Author: MJarmo

docs/Authentication.md

@@ -0,0 +1,117 @@
+# Authentication
+
+Summary of how authentication works in OpenTelemetry Collector using server- and client-side authenticators.
+
+## Modes
+
+- Server side: collector intercepts inbound HTTP/gRPC, extracts headers or query params, calls the server authenticator, returns
+  401/Unauthenticated on failure, forwards with enriched context on success.
+- Client side: collector wraps outbound HTTP or gRPC with authenticator-provided credentials so every request carries required headers,
+  tokens, or signing.
+
+## Authenticator types
+
+- Server (receivers): `basicauthextension`, `bearertokenauthextension`, `oidcauthextension`
+- Client (exporters): `asapauthextension`, `basicauthextension`, `bearertokenauthextension`, `oauth2clientauthextension`,
+  `sigv4authextension`
+
+## Notes
+
+For example for client-side OAuth2 in the collector you need an OAuth2 authorization server that exposes a token endpoint. The oauth2client
+extension is configured with that server’s token_url, your client_id/client_secret (and optional scopes/audience/TLS). It will call the
+token endpoint to obtain/refresh access tokens and inject Authorization: Bearer token on exporter requests. Without a reachable OAuth2
+server, the extension cannot get tokens.
+
+## Server-side example (basic auth)
+
+```yaml
+extensions:
+  basicauth/server:
+    htpasswd: ./htpasswd # file with user:hashed-password entries
+
+receivers:
+  otlp:
+    protocols:
+      http:
+        auth:
+          authenticator: basicauth/server
+      grpc:
+        auth:
+          authenticator: basicauth/server
+
+exporters:
+  debug: {}
+
+service:
+  extensions: [basicauth/server]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: []
+      exporters: [debug]
+    metrics:
+      receivers: [otlp]
+      processors: []
+      exporters: [debug]
+```
+
+## Client-side example (OAuth2)
+
+```yaml
+extensions:
+  oauth2client:
+    client_id: my-client
+    client_secret: supersecret
+    token_url: https://auth.example.com/oauth/token
+    scopes: [metrics.write]
+
+exporters:
+  otlphttp:
+    endpoint: https://backend.example.com
+    auth:
+      authenticator: oauth2client
+
+service:
+  extensions: [oauth2client]
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: []
+      exporters: [otlphttp]
+```
+
+## References
+
+- `opentelemetry-collector/config/configauth/README.md`
+
+## mTLS
+
+When using mutual TLS (mTLS) for authentication, both the client and server present their own certificates to verify each other's
+identities. For more details on setting up mTLS with OpenTelemetry Collector, refer to this guide:
+<https://dev.to/vipinvkmenon/setting-up-otel-collectors-for-mtls-4n4o>
+
+### in short
+
+#### mTLS receiver server
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        tls:
+          cert_file: /etc/certs/server-tls.pem
+          key_file: /etc/certs/server-tls.key
+          client_ca_file: /etc/certs/ca.pem
+```
+
+#### mTLS exporter client
+
+```yaml
+exporters:
+  otlp:
+    tls:
+      cert_file: /etc/certs/client-tls.pem
+      key_file: /etc/certs/client-tls.key
+      ca_file: /etc/certs/ca.pem
+```

docs/Metrics.md

@@ -0,0 +1,39 @@
+# Log pipeline metrics
+
+## Exporter send attempts (per exporter)
+
+- `otelcol_exporter_sent_log_records`
+- `otelcol_exporter_send_failed_log_records`
+- Counted per send attempt; any non-nil error marks the whole batch as failed. Retries add more increments.
+
+## Queue instrumentation (when `sending_queue` is enabled)
+
+- Gauges: queue size and queue capacity (in batches).
+- Counters: enqueue failures for logs.
+- Histograms: batch size (items) and batch size (bytes) recorded at enqueue time.
+
+## Consumed-side counters (behind feature gate)
+
+- Item and byte counts as data leaves processors toward exporters, labeled per component/exporter.
+- Requires `telemetry.newPipelineTelemetry` to be enabled; size counter depends on telemetry level.
+
+## Exporter helper chain
+
+- `BaseExporter` composes: timeout → retry → obsreport (span + sent/failed counters) → optional queue wrapper → actual exporter.
+- Counts are taken before downstream mutation so batching processors do not change the numerator.
+- Spans are started per export call with attributes: exporter name and `data_type=logs`.
+
+## Limitations and caveats
+
+- Attempt-based counting means retries inflate sent/failed totals; not unique record counts.
+- No partial success visibility: any error marks the entire batch failed.
+- Queue metrics are batch-based; histograms emit only when queueing is enabled.
+- Profiles signal is not instrumented by obsreport/queue.
+- Size counters rely on telemetry level/gate; if disabled you see only item counts.
+
+## What to watch
+
+- Delivery health: `otelcol_exporter_send_failed_log_records` vs `otelcol_exporter_sent_log_records`.
+- Backpressure: `otelcol_exporter_queue_size` vs `queue_capacity`; watch enqueue-failure counter for drops.
+- Batch shape: `otelcol_exporter_queue_batch_send_size` and `otelcol_exporter_queue_batch_send_size_bytes`.
+- Pipeline loss/refusal (with gate on): consumed item/size counters plus refusal/failure attributes from obsconsumer wrappers.