@unrdf/observability 26.4.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.
Files changed (31) hide show
  1. package/.eslintrc.cjs +10 -0
  2. package/IMPLEMENTATION-SUMMARY.md +478 -0
  3. package/LICENSE +21 -0
  4. package/README.md +482 -0
  5. package/capability-map.md +90 -0
  6. package/config/alert-rules.yml +269 -0
  7. package/config/prometheus.yml +136 -0
  8. package/dashboards/grafana-unrdf.json +798 -0
  9. package/dashboards/unrdf-workflow-dashboard.json +295 -0
  10. package/docs/OBSERVABILITY-PATTERNS.md +681 -0
  11. package/docs/OBSERVABILITY-RUNBOOK.md +554 -0
  12. package/examples/observability-demo.mjs +334 -0
  13. package/package.json +46 -0
  14. package/src/advanced-metrics.mjs +413 -0
  15. package/src/alerts/alert-manager.mjs +436 -0
  16. package/src/custom-events.mjs +558 -0
  17. package/src/distributed-tracing.mjs +352 -0
  18. package/src/exporters/grafana-exporter.mjs +415 -0
  19. package/src/index.mjs +61 -0
  20. package/src/metrics/workflow-metrics.mjs +346 -0
  21. package/src/receipts/anchor.mjs +155 -0
  22. package/src/receipts/index.mjs +62 -0
  23. package/src/receipts/merkle-tree.mjs +188 -0
  24. package/src/receipts/receipt-chain.mjs +209 -0
  25. package/src/receipts/receipt-schema.mjs +128 -0
  26. package/src/receipts/tamper-detection.mjs +219 -0
  27. package/test/advanced-metrics.test.mjs +302 -0
  28. package/test/custom-events.test.mjs +387 -0
  29. package/test/distributed-tracing.test.mjs +314 -0
  30. package/validation/observability-validation.mjs +366 -0
  31. package/vitest.config.mjs +25 -0
package/dashboards/grafana-unrdf.json ADDED
@@ -0,0 +1,798 @@
1
+ {
2
+ "annotations": {
3
+ "list": [
4
+ {
5
+ "builtIn": 1,
6
+ "datasource": {
7
+ "type": "grafana",
8
+ "uid": "-- Grafana --"
9
+ },
10
+ "enable": true,
11
+ "hide": true,
12
+ "iconColor": "rgba(0, 211, 255, 1)",
13
+ "name": "Annotations & Alerts",
14
+ "type": "dashboard"
15
+ }
16
+ ]
17
+ },
18
+ "editable": true,
19
+ "fiscalYearStartMonth": 0,
20
+ "graphTooltip": 1,
21
+ "id": null,
22
+ "links": [],
23
+ "panels": [
24
+ {
25
+ "collapsed": false,
26
+ "gridPos": {
27
+ "h": 1,
28
+ "w": 24,
29
+ "x": 0,
30
+ "y": 0
31
+ },
32
+ "id": 1,
33
+ "panels": [],
34
+ "title": "Business Metrics",
35
+ "type": "row"
36
+ },
37
+ {
38
+ "datasource": {
39
+ "type": "prometheus",
40
+ "uid": "${datasource}"
41
+ },
42
+ "fieldConfig": {
43
+ "defaults": {
44
+ "color": {
45
+ "mode": "palette-classic"
46
+ },
47
+ "custom": {
48
+ "axisBorderShow": false,
49
+ "axisCenteredZero": false,
50
+ "axisColorMode": "text",
51
+ "axisLabel": "",
52
+ "axisPlacement": "auto",
53
+ "barAlignment": 0,
54
+ "drawStyle": "line",
55
+ "fillOpacity": 10,
56
+ "gradientMode": "none",
57
+ "hideFrom": {
58
+ "tooltip": false,
59
+ "viz": false,
60
+ "legend": false
61
+ },
62
+ "insertNulls": false,
63
+ "lineInterpolation": "linear",
64
+ "lineWidth": 1,
65
+ "pointSize": 5,
66
+ "scaleDistribution": {
67
+ "type": "linear"
68
+ },
69
+ "showPoints": "never",
70
+ "spanNulls": false,
71
+ "stacking": {
72
+ "group": "A",
73
+ "mode": "none"
74
+ },
75
+ "thresholdsStyle": {
76
+ "mode": "off"
77
+ }
78
+ },
79
+ "mappings": [],
80
+ "thresholds": {
81
+ "mode": "absolute",
82
+ "steps": [
83
+ {
84
+ "color": "green",
85
+ "value": null
86
+ },
87
+ {
88
+ "color": "red",
89
+ "value": 80
90
+ }
91
+ ]
92
+ },
93
+ "unit": "percentunit"
94
+ },
95
+ "overrides": []
96
+ },
97
+ "gridPos": {
98
+ "h": 8,
99
+ "w": 12,
100
+ "x": 0,
101
+ "y": 1
102
+ },
103
+ "id": 2,
104
+ "options": {
105
+ "legend": {
106
+ "calcs": ["mean", "last"],
107
+ "displayMode": "table",
108
+ "placement": "bottom",
109
+ "showLegend": true
110
+ },
111
+ "tooltip": {
112
+ "mode": "multi",
113
+ "sort": "none"
114
+ }
115
+ },
116
+ "targets": [
117
+ {
118
+ "datasource": {
119
+ "type": "prometheus",
120
+ "uid": "${datasource}"
121
+ },
122
+ "expr": "rate(business_operations_total{result=\"success\"}[5m]) / rate(business_operations_total[5m])",
123
+ "legendFormat": "{{operation}} Success Rate",
124
+ "refId": "A"
125
+ }
126
+ ],
127
+ "title": "Operation Success Rate",
128
+ "type": "timeseries"
129
+ },
130
+ {
131
+ "datasource": {
132
+ "type": "prometheus",
133
+ "uid": "${datasource}"
134
+ },
135
+ "fieldConfig": {
136
+ "defaults": {
137
+ "color": {
138
+ "mode": "thresholds"
139
+ },
140
+ "mappings": [],
141
+ "thresholds": {
142
+ "mode": "absolute",
143
+ "steps": [
144
+ {
145
+ "color": "green",
146
+ "value": null
147
+ },
148
+ {
149
+ "color": "yellow",
150
+ "value": 10
151
+ },
152
+ {
153
+ "color": "red",
154
+ "value": 50
155
+ }
156
+ ]
157
+ },
158
+ "unit": "short"
159
+ },
160
+ "overrides": []
161
+ },
162
+ "gridPos": {
163
+ "h": 8,
164
+ "w": 12,
165
+ "x": 12,
166
+ "y": 1
167
+ },
168
+ "id": 3,
169
+ "options": {
170
+ "displayMode": "gradient",
171
+ "maxVizHeight": 300,
172
+ "minVizHeight": 16,
173
+ "minVizWidth": 8,
174
+ "namePlacement": "auto",
175
+ "orientation": "horizontal",
176
+ "reduceOptions": {
177
+ "calcs": ["lastNotNull"],
178
+ "fields": "",
179
+ "values": false
180
+ },
181
+ "showUnfilled": true,
182
+ "sizing": "auto",
183
+ "valueMode": "color"
184
+ },
185
+ "targets": [
186
+ {
187
+ "datasource": {
188
+ "type": "prometheus",
189
+ "uid": "${datasource}"
190
+ },
191
+ "expr": "sum by (operation, error_type) (rate(business_failures_by_type[5m]))",
192
+ "legendFormat": "{{operation}} - {{error_type}}",
193
+ "refId": "A"
194
+ }
195
+ ],
196
+ "title": "Failures by Error Type",
197
+ "type": "bargauge"
198
+ },
199
+ {
200
+ "collapsed": false,
201
+ "gridPos": {
202
+ "h": 1,
203
+ "w": 24,
204
+ "x": 0,
205
+ "y": 9
206
+ },
207
+ "id": 4,
208
+ "panels": [],
209
+ "title": "Latency Metrics",
210
+ "type": "row"
211
+ },
212
+ {
213
+ "datasource": {
214
+ "type": "prometheus",
215
+ "uid": "${datasource}"
216
+ },
217
+ "fieldConfig": {
218
+ "defaults": {
219
+ "color": {
220
+ "mode": "palette-classic"
221
+ },
222
+ "custom": {
223
+ "axisBorderShow": false,
224
+ "axisCenteredZero": false,
225
+ "axisColorMode": "text",
226
+ "axisLabel": "",
227
+ "axisPlacement": "auto",
228
+ "barAlignment": 0,
229
+ "drawStyle": "line",
230
+ "fillOpacity": 0,
231
+ "gradientMode": "none",
232
+ "hideFrom": {
233
+ "tooltip": false,
234
+ "viz": false,
235
+ "legend": false
236
+ },
237
+ "insertNulls": false,
238
+ "lineInterpolation": "linear",
239
+ "lineWidth": 1,
240
+ "pointSize": 5,
241
+ "scaleDistribution": {
242
+ "type": "linear"
243
+ },
244
+ "showPoints": "never",
245
+ "spanNulls": false,
246
+ "stacking": {
247
+ "group": "A",
248
+ "mode": "none"
249
+ },
250
+ "thresholdsStyle": {
251
+ "mode": "off"
252
+ }
253
+ },
254
+ "mappings": [],
255
+ "thresholds": {
256
+ "mode": "absolute",
257
+ "steps": [
258
+ {
259
+ "color": "green",
260
+ "value": null
261
+ }
262
+ ]
263
+ },
264
+ "unit": "ms"
265
+ },
266
+ "overrides": [
267
+ {
268
+ "matcher": {
269
+ "id": "byName",
270
+ "options": "P99"
271
+ },
272
+ "properties": [
273
+ {
274
+ "id": "color",
275
+ "value": {
276
+ "fixedColor": "red",
277
+ "mode": "fixed"
278
+ }
279
+ }
280
+ ]
281
+ },
282
+ {
283
+ "matcher": {
284
+ "id": "byName",
285
+ "options": "P95"
286
+ },
287
+ "properties": [
288
+ {
289
+ "id": "color",
290
+ "value": {
291
+ "fixedColor": "orange",
292
+ "mode": "fixed"
293
+ }
294
+ }
295
+ ]
296
+ },
297
+ {
298
+ "matcher": {
299
+ "id": "byName",
300
+ "options": "P90"
301
+ },
302
+ "properties": [
303
+ {
304
+ "id": "color",
305
+ "value": {
306
+ "fixedColor": "yellow",
307
+ "mode": "fixed"
308
+ }
309
+ }
310
+ ]
311
+ },
312
+ {
313
+ "matcher": {
314
+ "id": "byName",
315
+ "options": "P50"
316
+ },
317
+ "properties": [
318
+ {
319
+ "id": "color",
320
+ "value": {
321
+ "fixedColor": "green",
322
+ "mode": "fixed"
323
+ }
324
+ }
325
+ ]
326
+ }
327
+ ]
328
+ },
329
+ "gridPos": {
330
+ "h": 8,
331
+ "w": 24,
332
+ "x": 0,
333
+ "y": 10
334
+ },
335
+ "id": 5,
336
+ "options": {
337
+ "legend": {
338
+ "calcs": ["mean", "max"],
339
+ "displayMode": "table",
340
+ "placement": "right",
341
+ "showLegend": true
342
+ },
343
+ "tooltip": {
344
+ "mode": "multi",
345
+ "sort": "none"
346
+ }
347
+ },
348
+ "targets": [
349
+ {
350
+ "datasource": {
351
+ "type": "prometheus",
352
+ "uid": "${datasource}"
353
+ },
354
+ "expr": "histogram_quantile(0.50, rate(latency_operation_duration_ms_bucket[5m]))",
355
+ "legendFormat": "P50",
356
+ "refId": "A"
357
+ },
358
+ {
359
+ "datasource": {
360
+ "type": "prometheus",
361
+ "uid": "${datasource}"
362
+ },
363
+ "expr": "histogram_quantile(0.90, rate(latency_operation_duration_ms_bucket[5m]))",
364
+ "legendFormat": "P90",
365
+ "refId": "B"
366
+ },
367
+ {
368
+ "datasource": {
369
+ "type": "prometheus",
370
+ "uid": "${datasource}"
371
+ },
372
+ "expr": "histogram_quantile(0.95, rate(latency_operation_duration_ms_bucket[5m]))",
373
+ "legendFormat": "P95",
374
+ "refId": "C"
375
+ },
376
+ {
377
+ "datasource": {
378
+ "type": "prometheus",
379
+ "uid": "${datasource}"
380
+ },
381
+ "expr": "histogram_quantile(0.99, rate(latency_operation_duration_ms_bucket[5m]))",
382
+ "legendFormat": "P99",
383
+ "refId": "D"
384
+ }
385
+ ],
386
+ "title": "Latency Percentiles",
387
+ "type": "timeseries"
388
+ },
389
+ {
390
+ "collapsed": false,
391
+ "gridPos": {
392
+ "h": 1,
393
+ "w": 24,
394
+ "x": 0,
395
+ "y": 18
396
+ },
397
+ "id": 6,
398
+ "panels": [],
399
+ "title": "Throughput & Resource Metrics",
400
+ "type": "row"
401
+ },
402
+ {
403
+ "datasource": {
404
+ "type": "prometheus",
405
+ "uid": "${datasource}"
406
+ },
407
+ "fieldConfig": {
408
+ "defaults": {
409
+ "color": {
410
+ "mode": "palette-classic"
411
+ },
412
+ "custom": {
413
+ "axisBorderShow": false,
414
+ "axisCenteredZero": false,
415
+ "axisColorMode": "text",
416
+ "axisLabel": "",
417
+ "axisPlacement": "auto",
418
+ "barAlignment": 0,
419
+ "drawStyle": "line",
420
+ "fillOpacity": 10,
421
+ "gradientMode": "none",
422
+ "hideFrom": {
423
+ "tooltip": false,
424
+ "viz": false,
425
+ "legend": false
426
+ },
427
+ "insertNulls": false,
428
+ "lineInterpolation": "linear",
429
+ "lineWidth": 1,
430
+ "pointSize": 5,
431
+ "scaleDistribution": {
432
+ "type": "linear"
433
+ },
434
+ "showPoints": "never",
435
+ "spanNulls": false,
436
+ "stacking": {
437
+ "group": "A",
438
+ "mode": "none"
439
+ },
440
+ "thresholdsStyle": {
441
+ "mode": "off"
442
+ }
443
+ },
444
+ "mappings": [],
445
+ "thresholds": {
446
+ "mode": "absolute",
447
+ "steps": [
448
+ {
449
+ "color": "green",
450
+ "value": null
451
+ }
452
+ ]
453
+ },
454
+ "unit": "ops"
455
+ },
456
+ "overrides": []
457
+ },
458
+ "gridPos": {
459
+ "h": 8,
460
+ "w": 12,
461
+ "x": 0,
462
+ "y": 19
463
+ },
464
+ "id": 7,
465
+ "options": {
466
+ "legend": {
467
+ "calcs": ["mean", "max"],
468
+ "displayMode": "table",
469
+ "placement": "bottom",
470
+ "showLegend": true
471
+ },
472
+ "tooltip": {
473
+ "mode": "multi",
474
+ "sort": "none"
475
+ }
476
+ },
477
+ "targets": [
478
+ {
479
+ "datasource": {
480
+ "type": "prometheus",
481
+ "uid": "${datasource}"
482
+ },
483
+ "expr": "rate(business_operations_total[1m])",
484
+ "legendFormat": "{{operation}} ops/s",
485
+ "refId": "A"
486
+ }
487
+ ],
488
+ "title": "Throughput (ops/sec)",
489
+ "type": "timeseries"
490
+ },
491
+ {
492
+ "datasource": {
493
+ "type": "prometheus",
494
+ "uid": "${datasource}"
495
+ },
496
+ "fieldConfig": {
497
+ "defaults": {
498
+ "color": {
499
+ "mode": "palette-classic"
500
+ },
501
+ "custom": {
502
+ "axisBorderShow": false,
503
+ "axisCenteredZero": false,
504
+ "axisColorMode": "text",
505
+ "axisLabel": "",
506
+ "axisPlacement": "auto",
507
+ "barAlignment": 0,
508
+ "drawStyle": "line",
509
+ "fillOpacity": 10,
510
+ "gradientMode": "none",
511
+ "hideFrom": {
512
+ "tooltip": false,
513
+ "viz": false,
514
+ "legend": false
515
+ },
516
+ "insertNulls": false,
517
+ "lineInterpolation": "linear",
518
+ "lineWidth": 1,
519
+ "pointSize": 5,
520
+ "scaleDistribution": {
521
+ "type": "linear"
522
+ },
523
+ "showPoints": "never",
524
+ "spanNulls": false,
525
+ "stacking": {
526
+ "group": "A",
527
+ "mode": "normal"
528
+ },
529
+ "thresholdsStyle": {
530
+ "mode": "off"
531
+ }
532
+ },
533
+ "mappings": [],
534
+ "thresholds": {
535
+ "mode": "absolute",
536
+ "steps": [
537
+ {
538
+ "color": "green",
539
+ "value": null
540
+ }
541
+ ]
542
+ },
543
+ "unit": "bytes"
544
+ },
545
+ "overrides": []
546
+ },
547
+ "gridPos": {
548
+ "h": 8,
549
+ "w": 12,
550
+ "x": 12,
551
+ "y": 19
552
+ },
553
+ "id": 8,
554
+ "options": {
555
+ "legend": {
556
+ "calcs": ["mean", "last"],
557
+ "displayMode": "table",
558
+ "placement": "bottom",
559
+ "showLegend": true
560
+ },
561
+ "tooltip": {
562
+ "mode": "multi",
563
+ "sort": "none"
564
+ }
565
+ },
566
+ "targets": [
567
+ {
568
+ "datasource": {
569
+ "type": "prometheus",
570
+ "uid": "${datasource}"
571
+ },
572
+ "expr": "resource_heap_used_bytes",
573
+ "legendFormat": "Heap Used",
574
+ "refId": "A"
575
+ },
576
+ {
577
+ "datasource": {
578
+ "type": "prometheus",
579
+ "uid": "${datasource}"
580
+ },
581
+ "expr": "resource_heap_total_bytes",
582
+ "legendFormat": "Heap Total",
583
+ "refId": "B"
584
+ },
585
+ {
586
+ "datasource": {
587
+ "type": "prometheus",
588
+ "uid": "${datasource}"
589
+ },
590
+ "expr": "resource_external_bytes",
591
+ "legendFormat": "External",
592
+ "refId": "C"
593
+ }
594
+ ],
595
+ "title": "Memory Utilization",
596
+ "type": "timeseries"
597
+ },
598
+ {
599
+ "collapsed": false,
600
+ "gridPos": {
601
+ "h": 1,
602
+ "w": 24,
603
+ "x": 0,
604
+ "y": 27
605
+ },
606
+ "id": 9,
607
+ "panels": [],
608
+ "title": "Custom Events",
609
+ "type": "row"
610
+ },
611
+ {
612
+ "datasource": {
613
+ "type": "prometheus",
614
+ "uid": "${datasource}"
615
+ },
616
+ "fieldConfig": {
617
+ "defaults": {
618
+ "color": {
619
+ "mode": "palette-classic"
620
+ },
621
+ "custom": {
622
+ "hideFrom": {
623
+ "tooltip": false,
624
+ "viz": false,
625
+ "legend": false
626
+ }
627
+ },
628
+ "mappings": []
629
+ },
630
+ "overrides": []
631
+ },
632
+ "gridPos": {
633
+ "h": 8,
634
+ "w": 12,
635
+ "x": 0,
636
+ "y": 28
637
+ },
638
+ "id": 10,
639
+ "options": {
640
+ "displayLabels": ["percent"],
641
+ "legend": {
642
+ "displayMode": "table",
643
+ "placement": "right",
644
+ "showLegend": true,
645
+ "values": ["value", "percent"]
646
+ },
647
+ "pieType": "pie",
648
+ "reduceOptions": {
649
+ "calcs": ["lastNotNull"],
650
+ "fields": "",
651
+ "values": false
652
+ },
653
+ "tooltip": {
654
+ "mode": "multi",
655
+ "sort": "none"
656
+ }
657
+ },
658
+ "targets": [
659
+ {
660
+ "datasource": {
661
+ "type": "prometheus",
662
+ "uid": "${datasource}"
663
+ },
664
+ "expr": "sum by (event_type) (increase(event_total[1h]))",
665
+ "legendFormat": "{{event_type}}",
666
+ "refId": "A"
667
+ }
668
+ ],
669
+ "title": "Events by Type (1h)",
670
+ "type": "piechart"
671
+ },
672
+ {
673
+ "datasource": {
674
+ "type": "prometheus",
675
+ "uid": "${datasource}"
676
+ },
677
+ "fieldConfig": {
678
+ "defaults": {
679
+ "color": {
680
+ "mode": "palette-classic"
681
+ },
682
+ "custom": {
683
+ "axisBorderShow": false,
684
+ "axisCenteredZero": false,
685
+ "axisColorMode": "text",
686
+ "axisLabel": "",
687
+ "axisPlacement": "auto",
688
+ "barAlignment": 0,
689
+ "drawStyle": "line",
690
+ "fillOpacity": 10,
691
+ "gradientMode": "none",
692
+ "hideFrom": {
693
+ "tooltip": false,
694
+ "viz": false,
695
+ "legend": false
696
+ },
697
+ "insertNulls": false,
698
+ "lineInterpolation": "linear",
699
+ "lineWidth": 1,
700
+ "pointSize": 5,
701
+ "scaleDistribution": {
702
+ "type": "linear"
703
+ },
704
+ "showPoints": "never",
705
+ "spanNulls": false,
706
+ "stacking": {
707
+ "group": "A",
708
+ "mode": "normal"
709
+ },
710
+ "thresholdsStyle": {
711
+ "mode": "off"
712
+ }
713
+ },
714
+ "mappings": [],
715
+ "thresholds": {
716
+ "mode": "absolute",
717
+ "steps": [
718
+ {
719
+ "color": "green",
720
+ "value": null
721
+ }
722
+ ]
723
+ },
724
+ "unit": "short"
725
+ },
726
+ "overrides": []
727
+ },
728
+ "gridPos": {
729
+ "h": 8,
730
+ "w": 12,
731
+ "x": 12,
732
+ "y": 28
733
+ },
734
+ "id": 11,
735
+ "options": {
736
+ "legend": {
737
+ "calcs": ["sum"],
738
+ "displayMode": "table",
739
+ "placement": "bottom",
740
+ "showLegend": true
741
+ },
742
+ "tooltip": {
743
+ "mode": "multi",
744
+ "sort": "none"
745
+ }
746
+ },
747
+ "targets": [
748
+ {
749
+ "datasource": {
750
+ "type": "prometheus",
751
+ "uid": "${datasource}"
752
+ },
753
+ "expr": "sum by (severity) (rate(event_total[5m]))",
754
+ "legendFormat": "{{severity}}",
755
+ "refId": "A"
756
+ }
757
+ ],
758
+ "title": "Events by Severity",
759
+ "type": "timeseries"
760
+ }
761
+ ],
762
+ "refresh": "10s",
763
+ "schemaVersion": 39,
764
+ "tags": ["unrdf", "observability", "otel"],
765
+ "templating": {
766
+ "list": [
767
+ {
768
+ "current": {
769
+ "selected": false,
770
+ "text": "Prometheus",
771
+ "value": "prometheus"
772
+ },
773
+ "hide": 0,
774
+ "includeAll": false,
775
+ "label": "Datasource",
776
+ "multi": false,
777
+ "name": "datasource",
778
+ "options": [],
779
+ "query": "prometheus",
780
+ "queryValue": "",
781
+ "refresh": 1,
782
+ "regex": "",
783
+ "skipUrlSync": false,
784
+ "type": "datasource"
785
+ }
786
+ ]
787
+ },
788
+ "time": {
789
+ "from": "now-1h",
790
+ "to": "now"
791
+ },
792
+ "timepicker": {},
793
+ "timezone": "browser",
794
+ "title": "UNRDF Observability Dashboard",
795
+ "uid": "unrdf-observability",
796
+ "version": 1,
797
+ "weekStart": ""
798
+ }