@primafuture/telemetry-structured-metadata 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -35,6 +35,74 @@ app.meta.json = "{\"request\":{\"id\":\"abc\",\"deletedAt\":null},\"missing\":{\
|
|
|
35
35
|
reconstruction. `raw` output is disabled by default and only passes through
|
|
36
36
|
OpenTelemetry-safe scalar or homogeneous array values.
|
|
37
37
|
|
|
38
|
+
## Options
|
|
39
|
+
|
|
40
|
+
All output modes are independent and can be enabled at the same time:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
encodeStructuredMetadata(metadata, {
|
|
44
|
+
flatten: {
|
|
45
|
+
enabled: true,
|
|
46
|
+
namespace: 'app',
|
|
47
|
+
valuePrefix: 'value',
|
|
48
|
+
typePrefix: 'type',
|
|
49
|
+
typeFields: 'when-needed',
|
|
50
|
+
},
|
|
51
|
+
json: {
|
|
52
|
+
enabled: true,
|
|
53
|
+
key: 'app.meta.json',
|
|
54
|
+
valueEncoding: 'typed',
|
|
55
|
+
typeKey: '$pfType',
|
|
56
|
+
},
|
|
57
|
+
raw: {
|
|
58
|
+
enabled: false,
|
|
59
|
+
},
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Defaults:
|
|
64
|
+
|
|
65
|
+
- `flatten.enabled = true`
|
|
66
|
+
- `flatten.namespace = "app"`
|
|
67
|
+
- `flatten.valuePrefix = "value"`
|
|
68
|
+
- `flatten.typePrefix = "type"`
|
|
69
|
+
- `flatten.typeFields = "when-needed"`
|
|
70
|
+
- `json.enabled = true`
|
|
71
|
+
- `json.key = "app.meta.json"`
|
|
72
|
+
- `json.valueEncoding = "typed"`
|
|
73
|
+
- `json.typeKey = "$pfType"`
|
|
74
|
+
- `raw.enabled = false`
|
|
75
|
+
|
|
76
|
+
`typeFields` controls `app.type.*` output:
|
|
77
|
+
|
|
78
|
+
- `when-needed`: emit type markers only for values that plain OTel attributes
|
|
79
|
+
cannot represent clearly, such as `null`, `undefined`, `Date`, `bigint`,
|
|
80
|
+
`Error`, empty objects/arrays, functions, symbols, circular references, and
|
|
81
|
+
unsupported objects.
|
|
82
|
+
- `always`: emit a type marker for every flattened value.
|
|
83
|
+
- `never`: do not emit type markers.
|
|
84
|
+
|
|
85
|
+
`json.valueEncoding = "typed"` preserves JavaScript-only values using the
|
|
86
|
+
configured type key. `plain-json` writes ordinary JSON instead: `Date` becomes an
|
|
87
|
+
ISO string, `bigint` becomes a string, and `undefined`/function/symbol values
|
|
88
|
+
follow normal JSON behavior.
|
|
89
|
+
|
|
90
|
+
`raw.enabled = true` is a compatibility mode. It passes through only OTel-safe
|
|
91
|
+
scalar values or homogeneous arrays. Nested objects never go through raw mode.
|
|
92
|
+
|
|
93
|
+
## Decode
|
|
94
|
+
|
|
95
|
+
`decodeStructuredMetadata(attributes)` reads the configured JSON key, defaulting
|
|
96
|
+
to `app.meta.json`, and reconstructs the metadata object from the JSON view.
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
const decoded = decodeStructuredMetadata(attributes);
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The decoder primarily uses JSON because flattened attributes are a query view,
|
|
103
|
+
not the source of truth for reconstruction. It also accepts Loki-style underscore
|
|
104
|
+
keys such as `app_meta_json`.
|
|
105
|
+
|
|
38
106
|
## Development
|
|
39
107
|
|
|
40
108
|
```bash
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@primafuture/telemetry-structured-metadata",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.2",
|
|
5
5
|
"description": "Shared structured metadata encoder for PrimaFuture telemetry libraries.",
|
|
6
6
|
"author": "PrimaFuture.cz s.r.o. <dev@primafuture.cz>",
|
|
7
7
|
"license": "ISC",
|