@superblocksteam/telemetry 2.0.171 → 2.0.173-next.0

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 (304) hide show
  1. package/dist/browser/console-logging.js +2 -7
  2. package/dist/browser/console-logging.js.map +1 -1
  3. package/dist/browser/early-console-buffer.js +12 -14
  4. package/dist/browser/early-console-buffer.js.map +1 -1
  5. package/dist/browser/index.js +12 -41
  6. package/dist/browser/index.js.map +1 -1
  7. package/dist/browser/init.d.ts +1 -1
  8. package/dist/browser/init.d.ts.map +1 -1
  9. package/dist/browser/init.js +42 -52
  10. package/dist/browser/init.js.map +1 -1
  11. package/dist/browser/instrumentations.js +11 -15
  12. package/dist/browser/instrumentations.js.map +1 -1
  13. package/dist/browser/logs.d.ts +1 -1
  14. package/dist/browser/logs.d.ts.map +1 -1
  15. package/dist/browser/logs.js +11 -18
  16. package/dist/browser/logs.js.map +1 -1
  17. package/dist/browser/metrics.js +9 -12
  18. package/dist/browser/metrics.js.map +1 -1
  19. package/dist/browser/resilient-exporter.d.ts +1 -1
  20. package/dist/browser/resilient-exporter.d.ts.map +1 -1
  21. package/dist/browser/resilient-exporter.js +8 -12
  22. package/dist/browser/resilient-exporter.js.map +1 -1
  23. package/dist/browser/sanitizer.js +2 -6
  24. package/dist/browser/sanitizer.js.map +1 -1
  25. package/dist/browser/traced-socket.js +14 -18
  26. package/dist/browser/traced-socket.js.map +1 -1
  27. package/dist/common/contracts/tier2-traces.js +33 -44
  28. package/dist/common/contracts/tier2-traces.js.map +1 -1
  29. package/dist/common/deployment-type.js +5 -8
  30. package/dist/common/deployment-type.js.map +1 -1
  31. package/dist/common/guardrails.js +26 -38
  32. package/dist/common/guardrails.js.map +1 -1
  33. package/dist/common/index.js +8 -24
  34. package/dist/common/index.js.map +1 -1
  35. package/dist/common/log-sanitizer.js +37 -55
  36. package/dist/common/log-sanitizer.js.map +1 -1
  37. package/dist/common/policy-evaluator.d.ts +1 -1
  38. package/dist/common/policy-evaluator.d.ts.map +1 -1
  39. package/dist/common/policy-evaluator.js +5 -9
  40. package/dist/common/policy-evaluator.js.map +1 -1
  41. package/dist/common/resource.js +18 -25
  42. package/dist/common/resource.js.map +1 -1
  43. package/dist/common/tier-hints.js +12 -22
  44. package/dist/common/tier-hints.js.map +1 -1
  45. package/dist/common/trace-sanitizer.js +6 -10
  46. package/dist/common/trace-sanitizer.js.map +1 -1
  47. package/dist/common/traced-socket-types.js +1 -2
  48. package/dist/common/traced-socket-types.js.map +1 -1
  49. package/dist/index.js +6 -38
  50. package/dist/index.js.map +1 -1
  51. package/dist/lint/forbidden-attributes.js +19 -24
  52. package/dist/lint/forbidden-attributes.js.map +1 -1
  53. package/dist/lint/index.js +1 -8
  54. package/dist/lint/index.js.map +1 -1
  55. package/dist/llmobs/index.js +2 -9
  56. package/dist/llmobs/index.js.map +1 -1
  57. package/dist/llmobs/tier1-exporter.js +6 -12
  58. package/dist/llmobs/tier1-exporter.js.map +1 -1
  59. package/dist/llmobs/tier2-summarizer.js +1 -5
  60. package/dist/llmobs/tier2-summarizer.js.map +1 -1
  61. package/dist/node/dynamic-attribute-processor.js +2 -7
  62. package/dist/node/dynamic-attribute-processor.js.map +1 -1
  63. package/dist/node/exporters/resilient-exporter.d.ts +1 -1
  64. package/dist/node/exporters/resilient-exporter.d.ts.map +1 -1
  65. package/dist/node/exporters/resilient-exporter.js +8 -12
  66. package/dist/node/exporters/resilient-exporter.js.map +1 -1
  67. package/dist/node/index.js +7 -26
  68. package/dist/node/index.js.map +1 -1
  69. package/dist/node/init.d.ts +3 -3
  70. package/dist/node/init.d.ts.map +1 -1
  71. package/dist/node/init.js +66 -72
  72. package/dist/node/init.js.map +1 -1
  73. package/dist/node/local-obs-mode.js +1 -4
  74. package/dist/node/local-obs-mode.js.map +1 -1
  75. package/dist/node/log-processor.d.ts +1 -1
  76. package/dist/node/log-processor.d.ts.map +1 -1
  77. package/dist/node/log-processor.js +47 -55
  78. package/dist/node/log-processor.js.map +1 -1
  79. package/dist/node/metrics-client.js +1 -5
  80. package/dist/node/metrics-client.js.map +1 -1
  81. package/dist/node/safe-logger.js +8 -12
  82. package/dist/node/safe-logger.js.map +1 -1
  83. package/dist/node/sanitizing-processor.d.ts +2 -2
  84. package/dist/node/sanitizing-processor.d.ts.map +1 -1
  85. package/dist/node/sanitizing-processor.js +6 -10
  86. package/dist/node/sanitizing-processor.js.map +1 -1
  87. package/dist/node/service-tracers.js +7 -10
  88. package/dist/node/service-tracers.js.map +1 -1
  89. package/dist/node/traced-socket.d.ts +3 -3
  90. package/dist/node/traced-socket.d.ts.map +1 -1
  91. package/dist/node/traced-socket.js +48 -52
  92. package/dist/node/traced-socket.js.map +1 -1
  93. package/dist/npm-registry/emitter.js +34 -47
  94. package/dist/npm-registry/emitter.js.map +1 -1
  95. package/dist/npm-registry/index.js +3 -19
  96. package/dist/npm-registry/index.js.map +1 -1
  97. package/dist/npm-registry/sanitize.js +16 -27
  98. package/dist/npm-registry/sanitize.js.map +1 -1
  99. package/dist/npm-registry/spans.js +7 -12
  100. package/dist/npm-registry/spans.js.map +1 -1
  101. package/dist/testing/in-memory-exporter.d.ts +1 -1
  102. package/dist/testing/in-memory-exporter.d.ts.map +1 -1
  103. package/dist/testing/in-memory-exporter.js +6 -12
  104. package/dist/testing/in-memory-exporter.js.map +1 -1
  105. package/dist/testing/index.js +3 -15
  106. package/dist/testing/index.js.map +1 -1
  107. package/dist/testing/metrics-capture.js +12 -15
  108. package/dist/testing/metrics-capture.js.map +1 -1
  109. package/dist/testing/test-init.js +24 -31
  110. package/dist/testing/test-init.js.map +1 -1
  111. package/dist/types/index.js +1 -17
  112. package/dist/types/index.js.map +1 -1
  113. package/dist/types/policy.js +21 -24
  114. package/dist/types/policy.js.map +1 -1
  115. package/package.json +11 -17
  116. package/dist-esm/browser/console-logging.d.ts +0 -18
  117. package/dist-esm/browser/console-logging.d.ts.map +0 -1
  118. package/dist-esm/browser/console-logging.js +0 -27
  119. package/dist-esm/browser/console-logging.js.map +0 -1
  120. package/dist-esm/browser/early-console-buffer.d.ts +0 -49
  121. package/dist-esm/browser/early-console-buffer.d.ts.map +0 -1
  122. package/dist-esm/browser/early-console-buffer.js +0 -181
  123. package/dist-esm/browser/early-console-buffer.js.map +0 -1
  124. package/dist-esm/browser/index.d.ts +0 -18
  125. package/dist-esm/browser/index.d.ts.map +0 -1
  126. package/dist-esm/browser/index.js +0 -23
  127. package/dist-esm/browser/index.js.map +0 -1
  128. package/dist-esm/browser/init.d.ts +0 -100
  129. package/dist-esm/browser/init.d.ts.map +0 -1
  130. package/dist-esm/browser/init.js +0 -317
  131. package/dist-esm/browser/init.js.map +0 -1
  132. package/dist-esm/browser/instrumentations.d.ts +0 -67
  133. package/dist-esm/browser/instrumentations.d.ts.map +0 -1
  134. package/dist-esm/browser/instrumentations.js +0 -79
  135. package/dist-esm/browser/instrumentations.js.map +0 -1
  136. package/dist-esm/browser/logs.d.ts +0 -57
  137. package/dist-esm/browser/logs.d.ts.map +0 -1
  138. package/dist-esm/browser/logs.js +0 -80
  139. package/dist-esm/browser/logs.js.map +0 -1
  140. package/dist-esm/browser/metrics.d.ts +0 -29
  141. package/dist-esm/browser/metrics.d.ts.map +0 -1
  142. package/dist-esm/browser/metrics.js +0 -46
  143. package/dist-esm/browser/metrics.js.map +0 -1
  144. package/dist-esm/browser/resilient-exporter.d.ts +0 -43
  145. package/dist-esm/browser/resilient-exporter.d.ts.map +0 -1
  146. package/dist-esm/browser/resilient-exporter.js +0 -84
  147. package/dist-esm/browser/resilient-exporter.js.map +0 -1
  148. package/dist-esm/browser/sanitizer.d.ts +0 -35
  149. package/dist-esm/browser/sanitizer.d.ts.map +0 -1
  150. package/dist-esm/browser/sanitizer.js +0 -207
  151. package/dist-esm/browser/sanitizer.js.map +0 -1
  152. package/dist-esm/browser/traced-socket.d.ts +0 -102
  153. package/dist-esm/browser/traced-socket.d.ts.map +0 -1
  154. package/dist-esm/browser/traced-socket.js +0 -199
  155. package/dist-esm/browser/traced-socket.js.map +0 -1
  156. package/dist-esm/common/contracts/tier2-traces.d.ts +0 -116
  157. package/dist-esm/common/contracts/tier2-traces.d.ts.map +0 -1
  158. package/dist-esm/common/contracts/tier2-traces.js +0 -725
  159. package/dist-esm/common/contracts/tier2-traces.js.map +0 -1
  160. package/dist-esm/common/deployment-type.d.ts +0 -18
  161. package/dist-esm/common/deployment-type.d.ts.map +0 -1
  162. package/dist-esm/common/deployment-type.js +0 -27
  163. package/dist-esm/common/deployment-type.js.map +0 -1
  164. package/dist-esm/common/guardrails.d.ts +0 -132
  165. package/dist-esm/common/guardrails.d.ts.map +0 -1
  166. package/dist-esm/common/guardrails.js +0 -230
  167. package/dist-esm/common/guardrails.js.map +0 -1
  168. package/dist-esm/common/index.d.ts +0 -17
  169. package/dist-esm/common/index.d.ts.map +0 -1
  170. package/dist-esm/common/index.js +0 -17
  171. package/dist-esm/common/index.js.map +0 -1
  172. package/dist-esm/common/log-sanitizer.d.ts +0 -163
  173. package/dist-esm/common/log-sanitizer.d.ts.map +0 -1
  174. package/dist-esm/common/log-sanitizer.js +0 -745
  175. package/dist-esm/common/log-sanitizer.js.map +0 -1
  176. package/dist-esm/common/policy-evaluator.d.ts +0 -103
  177. package/dist-esm/common/policy-evaluator.d.ts.map +0 -1
  178. package/dist-esm/common/policy-evaluator.js +0 -196
  179. package/dist-esm/common/policy-evaluator.js.map +0 -1
  180. package/dist-esm/common/resource.d.ts +0 -79
  181. package/dist-esm/common/resource.d.ts.map +0 -1
  182. package/dist-esm/common/resource.js +0 -121
  183. package/dist-esm/common/resource.js.map +0 -1
  184. package/dist-esm/common/tier-hints.d.ts +0 -182
  185. package/dist-esm/common/tier-hints.d.ts.map +0 -1
  186. package/dist-esm/common/tier-hints.js +0 -199
  187. package/dist-esm/common/tier-hints.js.map +0 -1
  188. package/dist-esm/common/trace-sanitizer.d.ts +0 -82
  189. package/dist-esm/common/trace-sanitizer.d.ts.map +0 -1
  190. package/dist-esm/common/trace-sanitizer.js +0 -230
  191. package/dist-esm/common/trace-sanitizer.js.map +0 -1
  192. package/dist-esm/common/traced-socket-types.d.ts +0 -43
  193. package/dist-esm/common/traced-socket-types.d.ts.map +0 -1
  194. package/dist-esm/common/traced-socket-types.js +0 -16
  195. package/dist-esm/common/traced-socket-types.js.map +0 -1
  196. package/dist-esm/index.d.ts +0 -45
  197. package/dist-esm/index.d.ts.map +0 -1
  198. package/dist-esm/index.js +0 -56
  199. package/dist-esm/index.js.map +0 -1
  200. package/dist-esm/lint/forbidden-attributes.d.ts +0 -149
  201. package/dist-esm/lint/forbidden-attributes.d.ts.map +0 -1
  202. package/dist-esm/lint/forbidden-attributes.js +0 -210
  203. package/dist-esm/lint/forbidden-attributes.js.map +0 -1
  204. package/dist-esm/lint/index.d.ts +0 -9
  205. package/dist-esm/lint/index.d.ts.map +0 -1
  206. package/dist-esm/lint/index.js +0 -9
  207. package/dist-esm/lint/index.js.map +0 -1
  208. package/dist-esm/llmobs/index.d.ts +0 -22
  209. package/dist-esm/llmobs/index.d.ts.map +0 -1
  210. package/dist-esm/llmobs/index.js +0 -22
  211. package/dist-esm/llmobs/index.js.map +0 -1
  212. package/dist-esm/llmobs/tier1-exporter.d.ts +0 -146
  213. package/dist-esm/llmobs/tier1-exporter.d.ts.map +0 -1
  214. package/dist-esm/llmobs/tier1-exporter.js +0 -193
  215. package/dist-esm/llmobs/tier1-exporter.js.map +0 -1
  216. package/dist-esm/llmobs/tier2-summarizer.d.ts +0 -268
  217. package/dist-esm/llmobs/tier2-summarizer.d.ts.map +0 -1
  218. package/dist-esm/llmobs/tier2-summarizer.js +0 -652
  219. package/dist-esm/llmobs/tier2-summarizer.js.map +0 -1
  220. package/dist-esm/node/dynamic-attribute-processor.d.ts +0 -43
  221. package/dist-esm/node/dynamic-attribute-processor.d.ts.map +0 -1
  222. package/dist-esm/node/dynamic-attribute-processor.js +0 -74
  223. package/dist-esm/node/dynamic-attribute-processor.js.map +0 -1
  224. package/dist-esm/node/exporters/resilient-exporter.d.ts +0 -91
  225. package/dist-esm/node/exporters/resilient-exporter.d.ts.map +0 -1
  226. package/dist-esm/node/exporters/resilient-exporter.js +0 -132
  227. package/dist-esm/node/exporters/resilient-exporter.js.map +0 -1
  228. package/dist-esm/node/index.d.ts +0 -13
  229. package/dist-esm/node/index.d.ts.map +0 -1
  230. package/dist-esm/node/index.js +0 -13
  231. package/dist-esm/node/index.js.map +0 -1
  232. package/dist-esm/node/init.d.ts +0 -97
  233. package/dist-esm/node/init.d.ts.map +0 -1
  234. package/dist-esm/node/init.js +0 -359
  235. package/dist-esm/node/init.js.map +0 -1
  236. package/dist-esm/node/local-obs-mode.d.ts +0 -17
  237. package/dist-esm/node/local-obs-mode.d.ts.map +0 -1
  238. package/dist-esm/node/local-obs-mode.js +0 -19
  239. package/dist-esm/node/local-obs-mode.js.map +0 -1
  240. package/dist-esm/node/log-processor.d.ts +0 -132
  241. package/dist-esm/node/log-processor.d.ts.map +0 -1
  242. package/dist-esm/node/log-processor.js +0 -389
  243. package/dist-esm/node/log-processor.js.map +0 -1
  244. package/dist-esm/node/metrics-client.d.ts +0 -88
  245. package/dist-esm/node/metrics-client.d.ts.map +0 -1
  246. package/dist-esm/node/metrics-client.js +0 -205
  247. package/dist-esm/node/metrics-client.js.map +0 -1
  248. package/dist-esm/node/safe-logger.d.ts +0 -55
  249. package/dist-esm/node/safe-logger.d.ts.map +0 -1
  250. package/dist-esm/node/safe-logger.js +0 -154
  251. package/dist-esm/node/safe-logger.js.map +0 -1
  252. package/dist-esm/node/sanitizing-processor.d.ts +0 -67
  253. package/dist-esm/node/sanitizing-processor.d.ts.map +0 -1
  254. package/dist-esm/node/sanitizing-processor.js +0 -163
  255. package/dist-esm/node/sanitizing-processor.js.map +0 -1
  256. package/dist-esm/node/service-tracers.d.ts +0 -52
  257. package/dist-esm/node/service-tracers.d.ts.map +0 -1
  258. package/dist-esm/node/service-tracers.js +0 -78
  259. package/dist-esm/node/service-tracers.js.map +0 -1
  260. package/dist-esm/node/traced-socket.d.ts +0 -120
  261. package/dist-esm/node/traced-socket.d.ts.map +0 -1
  262. package/dist-esm/node/traced-socket.js +0 -334
  263. package/dist-esm/node/traced-socket.js.map +0 -1
  264. package/dist-esm/npm-registry/emitter.d.ts +0 -330
  265. package/dist-esm/npm-registry/emitter.d.ts.map +0 -1
  266. package/dist-esm/npm-registry/emitter.js +0 -546
  267. package/dist-esm/npm-registry/emitter.js.map +0 -1
  268. package/dist-esm/npm-registry/index.d.ts +0 -12
  269. package/dist-esm/npm-registry/index.d.ts.map +0 -1
  270. package/dist-esm/npm-registry/index.js +0 -12
  271. package/dist-esm/npm-registry/index.js.map +0 -1
  272. package/dist-esm/npm-registry/sanitize.d.ts +0 -174
  273. package/dist-esm/npm-registry/sanitize.d.ts.map +0 -1
  274. package/dist-esm/npm-registry/sanitize.js +0 -331
  275. package/dist-esm/npm-registry/sanitize.js.map +0 -1
  276. package/dist-esm/npm-registry/spans.d.ts +0 -61
  277. package/dist-esm/npm-registry/spans.d.ts.map +0 -1
  278. package/dist-esm/npm-registry/spans.js +0 -86
  279. package/dist-esm/npm-registry/spans.js.map +0 -1
  280. package/dist-esm/package.json +0 -1
  281. package/dist-esm/testing/in-memory-exporter.d.ts +0 -179
  282. package/dist-esm/testing/in-memory-exporter.d.ts.map +0 -1
  283. package/dist-esm/testing/in-memory-exporter.js +0 -250
  284. package/dist-esm/testing/in-memory-exporter.js.map +0 -1
  285. package/dist-esm/testing/index.d.ts +0 -9
  286. package/dist-esm/testing/index.d.ts.map +0 -1
  287. package/dist-esm/testing/index.js +0 -9
  288. package/dist-esm/testing/index.js.map +0 -1
  289. package/dist-esm/testing/metrics-capture.d.ts +0 -29
  290. package/dist-esm/testing/metrics-capture.d.ts.map +0 -1
  291. package/dist-esm/testing/metrics-capture.js +0 -71
  292. package/dist-esm/testing/metrics-capture.js.map +0 -1
  293. package/dist-esm/testing/test-init.d.ts +0 -80
  294. package/dist-esm/testing/test-init.d.ts.map +0 -1
  295. package/dist-esm/testing/test-init.js +0 -137
  296. package/dist-esm/testing/test-init.js.map +0 -1
  297. package/dist-esm/types/index.d.ts +0 -84
  298. package/dist-esm/types/index.d.ts.map +0 -1
  299. package/dist-esm/types/index.js +0 -7
  300. package/dist-esm/types/index.js.map +0 -1
  301. package/dist-esm/types/policy.d.ts +0 -92
  302. package/dist-esm/types/policy.d.ts.map +0 -1
  303. package/dist-esm/types/policy.js +0 -122
  304. package/dist-esm/types/policy.js.map +0 -1
@@ -1,182 +0,0 @@
1
- /**
2
- * Tier Policy Hints
3
- *
4
- * SDK-level hints that inform the OTEL Collector how to route spans.
5
- * These are HINTS, not guarantees — the Collector makes final routing decisions.
6
- *
7
- * NOTE: This is different from tier TAGS (which indicate which pipeline processed
8
- * a span). Hints are prescriptive ("please route this way"), tags are descriptive
9
- * ("this was processed by Tier X"). The Collector adds tier tags; the SDK adds hints.
10
- *
11
- * See: engineering/projects/o11y-refactor/proposals/sdk-tier-policy-hints.md
12
- */
13
- import type { Span } from "@opentelemetry/api";
14
- /**
15
- * The attribute key used for tier policy hints.
16
- * Collector filters on this attribute to make routing decisions.
17
- */
18
- export declare const TIER_HINT_ATTRIBUTE = "superblocks.tier_hint";
19
- /**
20
- * Tier policy hints that inform the Collector how to route spans.
21
- *
22
- * These are HINTS, not guarantees — the Collector makes final routing decisions
23
- * based on its configuration. In cloud-prem deployments, the Collector respects
24
- * these hints to control which tiers receive the span.
25
- *
26
- * @example
27
- * ```typescript
28
- * import { trace } from '@opentelemetry/api';
29
- * import { TierPolicyHint, TIER_HINT_ATTRIBUTE } from '@superblocksteam/telemetry';
30
- *
31
- * const span = tracer.startSpan('sensitive_operation');
32
- * span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
33
- * ```
34
- */
35
- export declare enum TierPolicyHint {
36
- /**
37
- * Route to Tier 1 only. Do not export to Tier 2 or Tier 3.
38
- *
39
- * Use for:
40
- * - Spans containing customer secrets or credentials
41
- * - Highly sensitive customer data that must not leave their environment
42
- * - Debug/diagnostic spans that should remain local
43
- *
44
- * The span will be stored in the customer's Tier 1 backend (e.g., Tempo)
45
- * but will NOT be exported to Superblocks (Tier 2) or AI analytics (Tier 3).
46
- */
47
- TIER1_ONLY = "tier1_only",
48
- /**
49
- * Include in Tier 3 (AI quality analysis) in addition to Tier 1 and Tier 2.
50
- *
51
- * Use for:
52
- * - GenAI spans that should be analyzed for quality metrics
53
- * - AI/LLM operations where prompts and responses are valuable for analysis
54
- * - Spans with AI quality signals (latency, token usage, etc.)
55
- *
56
- * The span will go to all tiers: Tier 1 (full fidelity), Tier 2 (sanitized),
57
- * and Tier 3 (AI analytics with identity stripped).
58
- */
59
- INCLUDE_TIER3 = "include_tier3",
60
- /**
61
- * Skip all external export. Tier 1 (local) only, no Tier 2/3.
62
- * Alias for TIER1_ONLY, kept for semantic clarity.
63
- *
64
- * Use for:
65
- * - High-cardinality diagnostic spans (cost control)
66
- * - Temporary debug spans that shouldn't persist
67
- * - Spans that are only useful for local debugging
68
- *
69
- * This is functionally equivalent to TIER1_ONLY but communicates
70
- * a different intent: "this is for cost/noise control" rather than
71
- * "this contains sensitive data."
72
- */
73
- SKIP_EXPORT = "skip_export"
74
- }
75
- /**
76
- * Set a tier policy hint on a span.
77
- *
78
- * This is a convenience function that sets the `superblocks.tier_hint` attribute.
79
- * You can also set the attribute directly if preferred.
80
- *
81
- * @param span - The span to set the hint on
82
- * @param hint - The tier policy hint
83
- *
84
- * @example
85
- * ```typescript
86
- * import { setTierHint, TierPolicyHint } from '@superblocksteam/telemetry';
87
- *
88
- * tracer.startActiveSpan('decrypt_secret', (span) => {
89
- * setTierHint(span, TierPolicyHint.TIER1_ONLY);
90
- * // ... perform operation
91
- * span.end();
92
- * });
93
- * ```
94
- */
95
- export declare function setTierHint(span: Span, hint: TierPolicyHint): void;
96
- /**
97
- * Mark a span as containing sensitive data that should not leave Tier 1.
98
- *
99
- * Use this for spans that handle customer secrets, credentials, or other
100
- * highly sensitive data that must remain in the customer's environment.
101
- *
102
- * @param span - The span to mark as sensitive
103
- *
104
- * @example
105
- * ```typescript
106
- * import { markSensitive } from '@superblocksteam/telemetry';
107
- *
108
- * tracer.startActiveSpan('decrypt_customer_secret', (span) => {
109
- * markSensitive(span);
110
- * // ... decrypt operation
111
- * span.end();
112
- * });
113
- * ```
114
- */
115
- export declare function markSensitive(span: Span): void;
116
- /**
117
- * Mark a span for AI quality analysis (Tier 3).
118
- *
119
- * Use this for GenAI spans that should be analyzed for quality metrics.
120
- * The span will go to all tiers, with Tier 3 receiving the content
121
- * (prompts/responses) for AI quality analysis.
122
- *
123
- * @param span - The span to mark for AI analysis
124
- *
125
- * @example
126
- * ```typescript
127
- * import { markForAIAnalysis } from '@superblocksteam/telemetry';
128
- *
129
- * tracer.startActiveSpan('gen_ai.chat', (span) => {
130
- * markForAIAnalysis(span);
131
- * span.setAttribute('gen_ai.system', 'anthropic');
132
- * // ... LLM call
133
- * span.end();
134
- * });
135
- * ```
136
- */
137
- export declare function markForAIAnalysis(span: Span): void;
138
- /**
139
- * Mark a span as debug-only (no export to Tier 2/3).
140
- *
141
- * Use this for high-cardinality diagnostic spans where you want to
142
- * control costs by preventing export to paid backends.
143
- *
144
- * @param span - The span to mark as debug-only
145
- *
146
- * @example
147
- * ```typescript
148
- * import { markDebugOnly } from '@superblocksteam/telemetry';
149
- *
150
- * tracer.startActiveSpan('debug.cache_lookup', (span) => {
151
- * markDebugOnly(span);
152
- * span.setAttribute('cache.key', cacheKey); // High cardinality OK
153
- * // ... lookup
154
- * span.end();
155
- * });
156
- * ```
157
- */
158
- export declare function markDebugOnly(span: Span): void;
159
- /**
160
- * Check if a span has a tier hint set.
161
- *
162
- * @param span - The span to check (must be a ReadableSpan with attributes)
163
- * @returns The tier hint if set, undefined otherwise
164
- */
165
- export declare function getTierHint(span: {
166
- attributes?: Record<string, unknown>;
167
- }): TierPolicyHint | undefined;
168
- /**
169
- * Check if a tier hint indicates the span should skip Tier 2 export.
170
- *
171
- * @param hint - The tier hint to check
172
- * @returns true if Tier 2 should be skipped
173
- */
174
- export declare function shouldSkipTier2(hint: TierPolicyHint | undefined): boolean;
175
- /**
176
- * Check if a tier hint indicates the span should be included in Tier 3.
177
- *
178
- * @param hint - The tier hint to check
179
- * @returns true if Tier 3 should be included
180
- */
181
- export declare function shouldIncludeTier3(hint: TierPolicyHint | undefined): boolean;
182
- //# sourceMappingURL=tier-hints.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tier-hints.d.ts","sourceRoot":"","sources":["../../src/common/tier-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,cAAc;IACxB;;;;;;;;;;OAUG;IACH,UAAU,eAAe;IAEzB;;;;;;;;;;OAUG;IACH,aAAa,kBAAkB;IAE/B;;;;;;;;;;;;OAYG;IACH,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAElE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAElD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GAAG,cAAc,GAAG,SAAS,CAS7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAE5E"}
@@ -1,199 +0,0 @@
1
- /**
2
- * Tier Policy Hints
3
- *
4
- * SDK-level hints that inform the OTEL Collector how to route spans.
5
- * These are HINTS, not guarantees — the Collector makes final routing decisions.
6
- *
7
- * NOTE: This is different from tier TAGS (which indicate which pipeline processed
8
- * a span). Hints are prescriptive ("please route this way"), tags are descriptive
9
- * ("this was processed by Tier X"). The Collector adds tier tags; the SDK adds hints.
10
- *
11
- * See: engineering/projects/o11y-refactor/proposals/sdk-tier-policy-hints.md
12
- */
13
- /**
14
- * The attribute key used for tier policy hints.
15
- * Collector filters on this attribute to make routing decisions.
16
- */
17
- export const TIER_HINT_ATTRIBUTE = "superblocks.tier_hint";
18
- /**
19
- * Tier policy hints that inform the Collector how to route spans.
20
- *
21
- * These are HINTS, not guarantees — the Collector makes final routing decisions
22
- * based on its configuration. In cloud-prem deployments, the Collector respects
23
- * these hints to control which tiers receive the span.
24
- *
25
- * @example
26
- * ```typescript
27
- * import { trace } from '@opentelemetry/api';
28
- * import { TierPolicyHint, TIER_HINT_ATTRIBUTE } from '@superblocksteam/telemetry';
29
- *
30
- * const span = tracer.startSpan('sensitive_operation');
31
- * span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
32
- * ```
33
- */
34
- export var TierPolicyHint;
35
- (function (TierPolicyHint) {
36
- /**
37
- * Route to Tier 1 only. Do not export to Tier 2 or Tier 3.
38
- *
39
- * Use for:
40
- * - Spans containing customer secrets or credentials
41
- * - Highly sensitive customer data that must not leave their environment
42
- * - Debug/diagnostic spans that should remain local
43
- *
44
- * The span will be stored in the customer's Tier 1 backend (e.g., Tempo)
45
- * but will NOT be exported to Superblocks (Tier 2) or AI analytics (Tier 3).
46
- */
47
- TierPolicyHint["TIER1_ONLY"] = "tier1_only";
48
- /**
49
- * Include in Tier 3 (AI quality analysis) in addition to Tier 1 and Tier 2.
50
- *
51
- * Use for:
52
- * - GenAI spans that should be analyzed for quality metrics
53
- * - AI/LLM operations where prompts and responses are valuable for analysis
54
- * - Spans with AI quality signals (latency, token usage, etc.)
55
- *
56
- * The span will go to all tiers: Tier 1 (full fidelity), Tier 2 (sanitized),
57
- * and Tier 3 (AI analytics with identity stripped).
58
- */
59
- TierPolicyHint["INCLUDE_TIER3"] = "include_tier3";
60
- /**
61
- * Skip all external export. Tier 1 (local) only, no Tier 2/3.
62
- * Alias for TIER1_ONLY, kept for semantic clarity.
63
- *
64
- * Use for:
65
- * - High-cardinality diagnostic spans (cost control)
66
- * - Temporary debug spans that shouldn't persist
67
- * - Spans that are only useful for local debugging
68
- *
69
- * This is functionally equivalent to TIER1_ONLY but communicates
70
- * a different intent: "this is for cost/noise control" rather than
71
- * "this contains sensitive data."
72
- */
73
- TierPolicyHint["SKIP_EXPORT"] = "skip_export";
74
- })(TierPolicyHint || (TierPolicyHint = {}));
75
- /**
76
- * Set a tier policy hint on a span.
77
- *
78
- * This is a convenience function that sets the `superblocks.tier_hint` attribute.
79
- * You can also set the attribute directly if preferred.
80
- *
81
- * @param span - The span to set the hint on
82
- * @param hint - The tier policy hint
83
- *
84
- * @example
85
- * ```typescript
86
- * import { setTierHint, TierPolicyHint } from '@superblocksteam/telemetry';
87
- *
88
- * tracer.startActiveSpan('decrypt_secret', (span) => {
89
- * setTierHint(span, TierPolicyHint.TIER1_ONLY);
90
- * // ... perform operation
91
- * span.end();
92
- * });
93
- * ```
94
- */
95
- export function setTierHint(span, hint) {
96
- span.setAttribute(TIER_HINT_ATTRIBUTE, hint);
97
- }
98
- /**
99
- * Mark a span as containing sensitive data that should not leave Tier 1.
100
- *
101
- * Use this for spans that handle customer secrets, credentials, or other
102
- * highly sensitive data that must remain in the customer's environment.
103
- *
104
- * @param span - The span to mark as sensitive
105
- *
106
- * @example
107
- * ```typescript
108
- * import { markSensitive } from '@superblocksteam/telemetry';
109
- *
110
- * tracer.startActiveSpan('decrypt_customer_secret', (span) => {
111
- * markSensitive(span);
112
- * // ... decrypt operation
113
- * span.end();
114
- * });
115
- * ```
116
- */
117
- export function markSensitive(span) {
118
- setTierHint(span, TierPolicyHint.TIER1_ONLY);
119
- }
120
- /**
121
- * Mark a span for AI quality analysis (Tier 3).
122
- *
123
- * Use this for GenAI spans that should be analyzed for quality metrics.
124
- * The span will go to all tiers, with Tier 3 receiving the content
125
- * (prompts/responses) for AI quality analysis.
126
- *
127
- * @param span - The span to mark for AI analysis
128
- *
129
- * @example
130
- * ```typescript
131
- * import { markForAIAnalysis } from '@superblocksteam/telemetry';
132
- *
133
- * tracer.startActiveSpan('gen_ai.chat', (span) => {
134
- * markForAIAnalysis(span);
135
- * span.setAttribute('gen_ai.system', 'anthropic');
136
- * // ... LLM call
137
- * span.end();
138
- * });
139
- * ```
140
- */
141
- export function markForAIAnalysis(span) {
142
- setTierHint(span, TierPolicyHint.INCLUDE_TIER3);
143
- }
144
- /**
145
- * Mark a span as debug-only (no export to Tier 2/3).
146
- *
147
- * Use this for high-cardinality diagnostic spans where you want to
148
- * control costs by preventing export to paid backends.
149
- *
150
- * @param span - The span to mark as debug-only
151
- *
152
- * @example
153
- * ```typescript
154
- * import { markDebugOnly } from '@superblocksteam/telemetry';
155
- *
156
- * tracer.startActiveSpan('debug.cache_lookup', (span) => {
157
- * markDebugOnly(span);
158
- * span.setAttribute('cache.key', cacheKey); // High cardinality OK
159
- * // ... lookup
160
- * span.end();
161
- * });
162
- * ```
163
- */
164
- export function markDebugOnly(span) {
165
- setTierHint(span, TierPolicyHint.SKIP_EXPORT);
166
- }
167
- /**
168
- * Check if a span has a tier hint set.
169
- *
170
- * @param span - The span to check (must be a ReadableSpan with attributes)
171
- * @returns The tier hint if set, undefined otherwise
172
- */
173
- export function getTierHint(span) {
174
- const hint = span.attributes?.[TIER_HINT_ATTRIBUTE];
175
- if (typeof hint === "string" &&
176
- Object.values(TierPolicyHint).includes(hint)) {
177
- return hint;
178
- }
179
- return undefined;
180
- }
181
- /**
182
- * Check if a tier hint indicates the span should skip Tier 2 export.
183
- *
184
- * @param hint - The tier hint to check
185
- * @returns true if Tier 2 should be skipped
186
- */
187
- export function shouldSkipTier2(hint) {
188
- return (hint === TierPolicyHint.TIER1_ONLY || hint === TierPolicyHint.SKIP_EXPORT);
189
- }
190
- /**
191
- * Check if a tier hint indicates the span should be included in Tier 3.
192
- *
193
- * @param hint - The tier hint to check
194
- * @returns true if Tier 3 should be included
195
- */
196
- export function shouldIncludeTier3(hint) {
197
- return hint === TierPolicyHint.INCLUDE_TIER3;
198
- }
199
- //# sourceMappingURL=tier-hints.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tier-hints.js","sourceRoot":"","sources":["../../src/common/tier-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,cAyCX;AAzCD,WAAY,cAAc;IACxB;;;;;;;;;;OAUG;IACH,2CAAyB,CAAA;IAEzB;;;;;;;;;;OAUG;IACH,iDAA+B,CAAA;IAE/B;;;;;;;;;;;;OAYG;IACH,6CAA2B,CAAA;AAC7B,CAAC,EAzCW,cAAc,KAAd,cAAc,QAyCzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,IAAoB;IAC1D,IAAI,CAAC,YAAY,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAU;IACtC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAU;IAC1C,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAU;IACtC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAE3B;IACC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,mBAAmB,CAAC,CAAC;IACpD,IACE,OAAO,IAAI,KAAK,QAAQ;QACxB,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,IAAsB,CAAC,EAC9D,CAAC;QACD,OAAO,IAAsB,CAAC;IAChC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAgC;IAC9D,OAAO,CACL,IAAI,KAAK,cAAc,CAAC,UAAU,IAAI,IAAI,KAAK,cAAc,CAAC,WAAW,CAC1E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgC;IACjE,OAAO,IAAI,KAAK,cAAc,CAAC,aAAa,CAAC;AAC/C,CAAC"}
@@ -1,82 +0,0 @@
1
- /**
2
- * Tier 2 Trace Sanitizer
3
- *
4
- * Sanitizes spans for Tier 2 export per epic-a3-sanitized-traces.
5
- * - Drops spans for high-volume, low-value routes (health, metrics)
6
- * - Drops spans not in the contract
7
- * - Drops forbidden attributes (PII, Tier 1 content)
8
- * - Drops high-cardinality attributes (e.g. binding_keys) when configured
9
- * - Hashes configured attributes using keyed HMAC (when hash config provided)
10
- * - Only includes attributes in the allowlist for each span type
11
- */
12
- import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
13
- import { type SpanDefinition } from "./contracts/tier2-traces.js";
14
- export interface HashConfig {
15
- secretKey: Buffer;
16
- salt: string;
17
- algorithm: "sha256" | "sha384" | "sha512";
18
- outputLengthBytes: number;
19
- }
20
- /**
21
- * Configuration for the trace sanitizer. Attribute sets and contract can vary by deployment type
22
- * (e.g. cloud vs cloud-prem). Use getTraceSanitizerAttributeSets(deploymentType)
23
- * from the contract to obtain sets for a given policy.
24
- */
25
- export interface TraceSanitizerOptions {
26
- hashConfig: HashConfig | null;
27
- forbiddenAttributes: Set<string>;
28
- droppedAttributes: Set<string>;
29
- hashedAttributes: Set<string>;
30
- /** Span definitions for name matching; defaults to TIER_2_TRACE_CONTRACT if omitted. */
31
- spanDefinitions?: SpanDefinition[];
32
- /** When true, span attributes are not filtered by allowedAttributes (pass-through). */
33
- attributeAllowlistPassthrough?: boolean;
34
- }
35
- export declare class TraceSanitizer {
36
- private readonly contractMap;
37
- private readonly hashConfig;
38
- private readonly forbiddenAttributes;
39
- private readonly droppedAttributes;
40
- private readonly hashedAttributes;
41
- private readonly attributeAllowlistPassthrough;
42
- constructor(options: TraceSanitizerOptions);
43
- /**
44
- * Check if a span should be exported to Tier 2.
45
- */
46
- shouldExport(span: ReadableSpan): boolean;
47
- /**
48
- * Sanitize span attributes for Tier 2 export.
49
- * Returns null if span should not be exported.
50
- *
51
- * Returns a ReadableSpan-like object that delegates to the original span for
52
- * spanContext() and other methods (spread does not copy prototype methods,
53
- * and the OTLP exporter calls span.spanContext()).
54
- */
55
- sanitize(span: ReadableSpan): ReadableSpan | null;
56
- private findMatchingDefinition;
57
- /**
58
- * Pattern matching: "*" matches any name; suffix wildcards (e.g. "HTTP POST *", "ws.*").
59
- * For "HTTP POST *", matches "HTTP POST" (exact) or "HTTP POST /path" (prefix + rest).
60
- */
61
- private matchesPattern;
62
- /**
63
- * Sanitize span links for Tier 2: link attributes are filtered the same way as
64
- * event attributes (forbidden dropped, high-cardinality dropped, hashed values).
65
- * Link context (trace/span IDs) is preserved.
66
- */
67
- private sanitizeLinks;
68
- /**
69
- * Sanitize span events for Tier 2: event attributes are filtered the same way as
70
- * span attributes (forbidden dropped, high-cardinality dropped, hashed values).
71
- * Event names and timestamps are preserved.
72
- */
73
- private sanitizeEvents;
74
- /**
75
- * Sanitize attributes that appear on events or links (no allowlist; only
76
- * drop forbidden/high-cardinality and hash hashed).
77
- */
78
- private sanitizeEventOrLinkAttributes;
79
- private sanitizeAttributes;
80
- private hashValue;
81
- }
82
- //# sourceMappingURL=trace-sanitizer.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"trace-sanitizer.d.ts","sourceRoot":"","sources":["../../src/common/trace-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,wFAAwF;IACxF,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,uFAAuF;IACvF,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAc;IAC/C,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAU;gBAE5C,OAAO,EAAE,qBAAqB;IAc1C;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;IAIzC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,IAAI;IA6CjD,OAAO,CAAC,sBAAsB;IAe9B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;OAGG;IACH,OAAO,CAAC,6BAA6B;IAkBrC,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,SAAS;CAYlB"}