docs+examples: document direction=ingress|egress, initiator and error_type enums; add cardinality relabel tips; provide Collector variants; add scripts/smoke-metrics.sh

examples/otel-collector.yaml

@@ -1,3 +1,20 @@
+# Variant A: Direct scrape of Newt (/metrics) via Prometheus (no Collector needed)
+# Note: Newt already exposes labels like site_id, protocol, direction. Do not promote
+# resource attributes into labels when scraping Newt directly.
+#
+# Example Prometheus scrape config:
+# global:
+#   scrape_interval: 15s
+# scrape_configs:
+#   - job_name: newt
+#     static_configs:
+#       - targets: ["newt:2112"]
+#
+# Variant B: Use OTEL Collector (Newt -> OTLP -> Collector -> Prometheus)
+# This pipeline scrapes metrics from the Collector's Prometheus exporter.
+# Labels are already on datapoints; promotion from resource is OPTIONAL and typically NOT required.
+# If you enable transform/promote below, ensure you do not duplicate labels.
+
 receivers:
   otlp:
     protocols:
@@ -13,20 +30,20 @@ processors:
     detectors: [env, system]
     timeout: 5s
   batch: {}
-  transform/promote:
-    # optional, damit fehlende Keys nicht die Pipeline abbrechen:
-    error_mode: ignore
-    metric_statements:
-      - context: datapoint
-        statements:
-          - set(attributes["service_instance_id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil
-          - set(attributes["site_id"], resource.attributes["site_id"]) where resource.attributes["site_id"] != nil
+  # OPTIONAL: Only enable if you need to promote resource attributes to labels.
+  # WARNING: Newt already provides site_id as a label; avoid double-promotion.
+  # transform/promote:
+  #   error_mode: ignore
+  #   metric_statements:
+  #     - context: datapoint
+  #       statements:
+  #         - set(attributes["service_instance_id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil
+  #         - set(attributes["site_id"], resource.attributes["site_id"]) where resource.attributes["site_id"] != nil
 
 exporters:
   prometheus:
     endpoint: ":8889"
     send_timestamps: true
-  # Falls du kein Remote-Write-Ziel hast, kommentiere es aus:
   # prometheusremotewrite:
   #   endpoint: http://mimir:9009/api/v1/push
   debug:
@@ -36,8 +53,8 @@ service:
   pipelines:
     metrics:
       receivers: [otlp]
-      processors: [memory_limiter, resourcedetection, transform/promote, batch]
-      exporters: [prometheus] # , prometheusremotewrite
+      processors: [memory_limiter, resourcedetection, batch] # add transform/promote if you really need it
+      exporters: [prometheus]
     traces:
       receivers: [otlp]
       processors: [memory_limiter, resourcedetection, batch]