@primafuture/telemetry-stack 0.1.0 → 0.3.0

package/README.md

@@ -195,10 +195,32 @@ curl -sS -X POST http://localhost:4318/v1/logs \
           \"timeUnixNano\": \"${TS}\",
           \"severityText\": \"INFO\",
           \"body\": {\"stringValue\": \"hello from telemetry-stack smoke test\"},
-          \"attributes\": [{
-            \"key\": \"log_type\",
-            \"value\": {\"stringValue\": \"smoke_test\"}
-          }]
+          \"attributes\": [
+            {
+              \"key\": \"app.value.log_type\",
+              \"value\": {\"stringValue\": \"smoke_test\"}
+            },
+            {
+              \"key\": \"app.value.route\",
+              \"value\": {\"stringValue\": \"/smoke\"}
+            },
+            {
+              \"key\": \"app.value.count\",
+              \"value\": {\"intValue\": \"3\"}
+            },
+            {
+              \"key\": \"app.value.parallel\",
+              \"value\": {\"boolValue\": true}
+            },
+            {
+              \"key\": \"app.type.deletedAt\",
+              \"value\": {\"stringValue\": \"null\"}
+            },
+            {
+              \"key\": \"app.meta.json\",
+              \"value\": {\"stringValue\": \"{\\\"log_type\\\":\\\"smoke_test\\\",\\\"route\\\":\\\"/smoke\\\",\\\"count\\\":3,\\\"parallel\\\":true,\\\"deletedAt\\\":null}\"}
+            }
+          ]
         }]
       }]
     }]
@@ -208,8 +230,86 @@ curl -sS -X POST http://localhost:4318/v1/logs \
 Query it from Loki:
 
 ```bash
-curl -G 'http://localhost:3100/loki/api/v1/query' \
-  --data-urlencode 'query={service_name="telemetry-smoke-test"}'
+curl -G 'http://localhost:3100/loki/api/v1/query_range' \
+  --data-urlencode 'query={loki_service_name="telemetry-smoke-test"}' \
+  --data-urlencode 'limit=5'
+```
+
+For Grafana trace-to-logs compatibility, the same log is also indexed by the
+legacy `service_name` label:
+
+```bash
+curl -G 'http://localhost:3100/loki/api/v1/query_range' \
+  --data-urlencode 'query={service_name="telemetry-smoke-test"}' \
+  --data-urlencode 'limit=5'
+```
+
+The returned log should expose application metadata under structured names such
+as `app_value_log_type`, `app_value_route`, `app_value_count`,
+`app_value_parallel`, `app_type_deletedAt`, and `app_meta_json`.
+OpenTelemetry metadata should be under `otel_*`, for example
+`otel_resource_service_name` and `otel_scope_name`.
+
+## Log Metadata in Loki
+
+PrimaFuture telemetry libraries encode application metadata before export. The
+query-friendly view uses `app.value.*` for values, `app.type.*` for type markers
+such as `null` or `undefined`, and `app.meta.json` for the JSON representation.
+Loki displays those dotted names as underscore names such as `app_value_route`.
+
+Legacy applications can still log plain metadata such as `count`, `parallel`, or
+`route`. Alloy wraps only those unprefixed legacy fields into `app.*`; it leaves
+already namespaced `app.*` metadata untouched.
+
+The stack uses these names:
+
+```text
+app_value_*           query-friendly application metadata values
+app_type_*            application metadata type markers
+app_meta_json         JSON application metadata representation
+app_*                 legacy application log attributes wrapped by Alloy
+otel_resource_*       OpenTelemetry resource attributes
+otel_scope_*          OpenTelemetry instrumentation scope attributes
+otel_log_*            OpenTelemetry log record fields
+loki_*                explicit Loki index labels
+service_name          legacy compatibility label for Grafana trace-to-logs
+```
+
+Examples:
+
+```text
+count                 -> app_value_count
+route                 -> app_value_route
+deletedAt: null       -> app_type_deletedAt = "null"
+metadata JSON         -> app_meta_json
+service.name          -> otel_resource_service_name
+instrumentation scope -> otel_scope_name
+trace id              -> otel_log_trace_id
+```
+
+Loki indexes only the low-cardinality resource labels configured in
+`loki.yaml`, such as `loki_service_name` and the compatibility `service_name`.
+Application and OpenTelemetry detail fields are stored as structured metadata,
+not as index labels. Query them after selecting a stream:
+
+```logql
+{loki_service_name="telemetry-dice-roller-example"}
+| trace_id="0242ac120002"
+| app_value_route="/roll"
+```
+
+Current Loki versions return structured metadata merged into the `stream` labels
+map in `query_range` responses. This is a Loki API behavior: the fields are still
+not index labels. Use `/loki/api/v1/labels` or `/loki/api/v1/series` to see the
+real indexed labels.
+
+If a query response is too noisy, reduce returned fields at query time without
+changing stored data:
+
+```logql
+{service_name="telemetry-dice-roller-example"}
+| trace_id="0242ac120002"
+| keep service_name, loki_service_name, trace_id, span_id
 ```
 
 ## Useful URLs

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@primafuture/telemetry-stack",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"type": "module",
 	"description": "Reusable PrimaFuture telemetry stack launcher powered by Docker Compose.",
 	"author": "PrimaFuture.cz s.r.o. <dev@primafuture.cz>",

package/stack/configs/config.alloy

@@ -1,13 +1,55 @@
 // Main Alloy pipeline for application telemetry.
 // It receives OTLP traces, metrics, and logs from apps and routes them to the stack.
 
-// Copy selected log attributes into resource attributes so Loki can index them as labels.
+// Normalize log metadata before Loki stores it as labels/structured metadata.
+// App-provided log attributes stay queryable under app.* and OTel/system data under otel.*.
 otelcol.processor.transform "loki_labels" {
+  error_mode = "ignore"
+
   log_statements {
     context = "log"
     statements = [
-      `set(resource.attributes["log_type"], attributes["log_type"]) where attributes["log_type"] != nil`,
-      `set(resource.attributes["log.file.path"], attributes["log.file.path"]) where attributes["log.file.path"] != nil`,
+      // Copy legacy application log attributes into app.* without wrapping already namespaced app.* fields again.
+      `merge_maps(log.cache, log.attributes, "upsert")`,
+      `delete_matching_keys(log.cache, "^app[.].*")`,
+      `delete_matching_keys(log.cache, "^otel[.].*")`,
+      `flatten(log.cache, "app", resolveConflicts=true)`,
+      `merge_maps(log.attributes, log.cache, "upsert")`,
+      `delete_matching_keys(log.cache, ".*")`,
+
+      // Copy original resource attributes into otel.resource.* before resource labels are rewritten for Loki.
+      `merge_maps(log.cache, resource.attributes, "upsert")`,
+      `flatten(log.cache, "otel.resource", resolveConflicts=true)`,
+      `merge_maps(log.attributes, log.cache, "upsert")`,
+      `delete_matching_keys(log.cache, ".*")`,
+
+      // Copy instrumentation scope data into otel.scope.*.
+      `merge_maps(log.cache, instrumentation_scope.attributes, "upsert")`,
+      `flatten(log.cache, "otel.scope.attributes", resolveConflicts=true)`,
+      `merge_maps(log.attributes, log.cache, "upsert")`,
+      `delete_matching_keys(log.cache, ".*")`,
+      `set(log.attributes["otel.scope.name"], instrumentation_scope.name) where instrumentation_scope.name != ""`,
+      `set(log.attributes["otel.scope.version"], instrumentation_scope.version) where instrumentation_scope.version != ""`,
+
+      // Duplicate intrinsic log fields into otel.log.* while leaving native trace/span fields intact for Grafana links.
+      `set(log.attributes["otel.log.severity_text"], log.severity_text) where log.severity_text != ""`,
+      `set(log.attributes["otel.log.severity_number"], log.severity_number)`,
+      `set(log.attributes["otel.log.trace_id"], log.trace_id.string) where log.trace_id.string != ""`,
+      `set(log.attributes["otel.log.span_id"], log.span_id.string) where log.span_id.string != ""`,
+      `set(log.attributes["otel.log.flags"], log.flags)`,
+
+      // Build explicit Loki labels from original values. Loki will normalize dots to underscores.
+      `set(resource.attributes["loki.service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil`,
+      `set(resource.attributes["loki.log.type"], log.attributes["log_type"]) where log.attributes["log_type"] != nil`,
+      `set(resource.attributes["loki.log.type"], log.attributes["value.log_type"]) where resource.attributes["loki.log.type"] == nil and log.attributes["value.log_type"] != nil`,
+      `set(resource.attributes["loki.log.type"], log.attributes["app.value.log_type"]) where resource.attributes["loki.log.type"] == nil and log.attributes["app.value.log_type"] != nil`,
+      `set(resource.attributes["loki.log.file.path"], log.attributes["log.file.path"]) where log.attributes["log.file.path"] != nil`,
+      `set(resource.attributes["loki.log.file.path"], log.attributes["value.log.file.path"]) where resource.attributes["loki.log.file.path"] == nil and log.attributes["value.log.file.path"] != nil`,
+      `set(resource.attributes["loki.log.file.path"], log.attributes["app.value.log.file.path"]) where resource.attributes["loki.log.file.path"] == nil and log.attributes["app.value.log.file.path"] != nil`,
+
+      // Keep only namespaced structured metadata, explicit Loki label resource attributes, and the legacy service.name label.
+      `keep_matching_keys(log.attributes, "^(app|otel)[.]")`,
+      `keep_matching_keys(resource.attributes, "^(loki[.].*|service[.]name)$")`,
     ]
   }
   output {

package/stack/configs/grafana-datasources.yaml

@@ -12,7 +12,7 @@ datasources:
   url: http://prometheus:9090
   basicAuth: false
   isDefault: false
-  version: 1
+  version: 2
   editable: true
   jsonData:
     httpMethod: GET
@@ -28,7 +28,7 @@ datasources:
   url: http://mimir:9009/prometheus
   basicAuth: false
   isDefault: false
-  version: 1
+  version: 2
   editable: true
   jsonData:
     httpMethod: GET
@@ -41,7 +41,7 @@ datasources:
   url: http://loki:3100
   basicAuth: false
   isDefault: false
-  version: 1
+  version: 2
   editable: true
   jsonData:
     httpMethod: GET
@@ -66,7 +66,7 @@ datasources:
   url: http://tempo:3200
   basicAuth: false
   isDefault: true
-  version: 1
+  version: 2
   editable: true
   apiVersion: 1
   uid: tempo-streaming-enabled
@@ -77,6 +77,16 @@ datasources:
     streamingEnabled:
       search: true
       metrics: true
+    tracesToLogsV2:
+      customQuery: false
+      datasourceUid: loki
+      filterBySpanID: true
+      filterByTraceID: true
+      spanEndTimeShift: 10s
+      spanStartTimeShift: "-10s"
+      tags:
+      - key: service.name
+        value: loki_service_name
 # This Tempo datasource keeps streaming disabled for links that need stable TraceQL behavior.
 - name: Tempo (no streaming)
   type: tempo
@@ -85,7 +95,7 @@ datasources:
   url: http://tempo:3200
   basicAuth: false
   isDefault: false
-  version: 1
+  version: 2
   editable: true
   apiVersion: 1
   uid: tempo-streaming-disabled
@@ -102,4 +112,4 @@ datasources:
       spanStartTimeShift: "-10s"
       tags:
       - key: service.name
-        value: service_name
+        value: loki_service_name

package/stack/templates/loki.yaml

@@ -52,12 +52,16 @@ compactor:
 # Keep demo logs for 7 days.
 limits_config:
   retention_period: 168h
+  # Keep synthetic Loki metadata out of the way; Alloy already namespaces these values.
+  discover_service_name: []
+  discover_log_levels: false
 
 # OTLP logs arrive with resource attributes. This list chooses which attributes
 # Loki indexes as labels; dots are converted to underscores in Loki/Grafana.
 distributor:
   otlp_config:
     default_resource_attributes_as_index_labels:
+      - loki.service.name
       - service.name
-      - log_type
-      - log.file.path
+      - loki.log.type
+      - loki.log.file.path