@primafuture/telemetry-stack 0.2.0 → 0.3.0

package/README.md

@@ -197,20 +197,28 @@ curl -sS -X POST http://localhost:4318/v1/logs \
           \"body\": {\"stringValue\": \"hello from telemetry-stack smoke test\"},
           \"attributes\": [
             {
-              \"key\": \"log_type\",
+              \"key\": \"app.value.log_type\",
               \"value\": {\"stringValue\": \"smoke_test\"}
             },
             {
-              \"key\": \"route\",
+              \"key\": \"app.value.route\",
               \"value\": {\"stringValue\": \"/smoke\"}
             },
             {
-              \"key\": \"count\",
+              \"key\": \"app.value.count\",
               \"value\": {\"intValue\": \"3\"}
             },
             {
-              \"key\": \"parallel\",
+              \"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}\"}
             }
           ]
         }]
@@ -236,21 +244,30 @@ curl -G 'http://localhost:3100/loki/api/v1/query_range' \
   --data-urlencode 'limit=5'
 ```
 
-The returned log should expose application metadata under `app_*`, for example
-`app_log_type`, `app_route`, `app_count`, and `app_parallel`. OpenTelemetry
-metadata should be under `otel_*`, for example `otel_resource_service_name` and
-`otel_scope_name`.
+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
 
-Applications can log plain metadata such as `count`, `parallel`, or `route`.
-Alloy normalizes those fields before Loki receives them, so application code does
-not need to add prefixes itself.
+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_*                 application log attributes
+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
@@ -261,8 +278,10 @@ service_name          legacy compatibility label for Grafana trace-to-logs
 Examples:
 
 ```text
-count                 -> app_count
-route                 -> app_route
+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
@@ -276,7 +295,7 @@ not as index labels. Query them after selecting a stream:
 ```logql
 {loki_service_name="telemetry-dice-roller-example"}
 | trace_id="0242ac120002"
-| app_route="/roll"
+| app_value_route="/roll"
 ```
 
 Current Loki versions return structured metadata merged into the `stream` labels

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@primafuture/telemetry-stack",
-	"version": "0.2.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

@@ -9,8 +9,10 @@ otelcol.processor.transform "loki_labels" {
   log_statements {
     context = "log"
     statements = [
-      // Copy application log attributes into app.* without requiring apps to prefix anything themselves.
+      // 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, ".*")`,
@@ -39,7 +41,11 @@ otelcol.processor.transform "loki_labels" {
       // 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)[.]")`,