logfire-sdk 5.3.0__py3-none-any.whl

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. _logfire_sdk/logfire/.agents/skills/logfire-evals/SKILL.md +170 -0
  2. _logfire_sdk/logfire/.agents/skills/logfire-gateway/SKILL.md +156 -0
  3. _logfire_sdk/logfire/.agents/skills/logfire-infrastructure/SKILL.md +61 -0
  4. _logfire_sdk/logfire/.agents/skills/logfire-infrastructure/references/collector/host-and-infra-metrics.md +229 -0
  5. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/SKILL.md +292 -0
  6. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/auth.md +100 -0
  7. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/ai-sdk.md +145 -0
  8. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/cloudflare-and-deno.md +99 -0
  9. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/frameworks.md +22 -0
  10. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/installation-and-env.md +75 -0
  11. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/nextjs.md +78 -0
  12. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/node-runtime.md +132 -0
  13. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/patterns.md +184 -0
  14. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/project-detection.md +43 -0
  15. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/react-browser.md +18 -0
  16. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/javascript/verification-troubleshooting.md +68 -0
  17. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/python/integrations.md +104 -0
  18. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/python/logging-patterns.md +120 -0
  19. _logfire_sdk/logfire/.agents/skills/logfire-instrumentation/references/rust/patterns.md +113 -0
  20. _logfire_sdk/logfire/.agents/skills/logfire-setup/SKILL.md +58 -0
  21. _logfire_sdk/logfire/.agents/skills/logfire-setup-offline.md +715 -0
  22. _logfire_sdk/logfire/__init__.py +226 -0
  23. _logfire_sdk/logfire/__main__.py +6 -0
  24. _logfire_sdk/logfire/_internal/__init__.py +14 -0
  25. _logfire_sdk/logfire/_internal/ast_utils.py +264 -0
  26. _logfire_sdk/logfire/_internal/async_.py +125 -0
  27. _logfire_sdk/logfire/_internal/auth.py +298 -0
  28. _logfire_sdk/logfire/_internal/auto_trace/__init__.py +74 -0
  29. _logfire_sdk/logfire/_internal/auto_trace/import_hook.py +137 -0
  30. _logfire_sdk/logfire/_internal/auto_trace/rewrite_ast.py +185 -0
  31. _logfire_sdk/logfire/_internal/auto_trace/types.py +44 -0
  32. _logfire_sdk/logfire/_internal/baggage.py +109 -0
  33. _logfire_sdk/logfire/_internal/cli/__init__.py +1081 -0
  34. _logfire_sdk/logfire/_internal/cli/ai_tools.py +231 -0
  35. _logfire_sdk/logfire/_internal/cli/auth.py +151 -0
  36. _logfire_sdk/logfire/_internal/cli/gateway.py +627 -0
  37. _logfire_sdk/logfire/_internal/cli/gateway_auth.py +313 -0
  38. _logfire_sdk/logfire/_internal/cli/prompt.py +50 -0
  39. _logfire_sdk/logfire/_internal/cli/run.py +590 -0
  40. _logfire_sdk/logfire/_internal/client.py +178 -0
  41. _logfire_sdk/logfire/_internal/collect_system_info.py +29 -0
  42. _logfire_sdk/logfire/_internal/config.py +2471 -0
  43. _logfire_sdk/logfire/_internal/config_params.py +343 -0
  44. _logfire_sdk/logfire/_internal/constants.py +185 -0
  45. _logfire_sdk/logfire/_internal/db_statement_summary.py +140 -0
  46. _logfire_sdk/logfire/_internal/exporters/__init__.py +1 -0
  47. _logfire_sdk/logfire/_internal/exporters/console.py +517 -0
  48. _logfire_sdk/logfire/_internal/exporters/dynamic_batch.py +49 -0
  49. _logfire_sdk/logfire/_internal/exporters/logs.py +30 -0
  50. _logfire_sdk/logfire/_internal/exporters/otlp.py +517 -0
  51. _logfire_sdk/logfire/_internal/exporters/processor_wrapper.py +652 -0
  52. _logfire_sdk/logfire/_internal/exporters/quiet_metrics.py +18 -0
  53. _logfire_sdk/logfire/_internal/exporters/remove_pending.py +45 -0
  54. _logfire_sdk/logfire/_internal/exporters/test.py +257 -0
  55. _logfire_sdk/logfire/_internal/exporters/wrapper.py +106 -0
  56. _logfire_sdk/logfire/_internal/formatter.py +379 -0
  57. _logfire_sdk/logfire/_internal/forwarding.py +585 -0
  58. _logfire_sdk/logfire/_internal/http_transport.py +193 -0
  59. _logfire_sdk/logfire/_internal/instrument.py +254 -0
  60. _logfire_sdk/logfire/_internal/integrations/__init__.py +1 -0
  61. _logfire_sdk/logfire/_internal/integrations/aiohttp_client.py +324 -0
  62. _logfire_sdk/logfire/_internal/integrations/aiohttp_server.py +22 -0
  63. _logfire_sdk/logfire/_internal/integrations/asgi.py +117 -0
  64. _logfire_sdk/logfire/_internal/integrations/asyncpg.py +21 -0
  65. _logfire_sdk/logfire/_internal/integrations/aws_lambda.py +36 -0
  66. _logfire_sdk/logfire/_internal/integrations/celery.py +20 -0
  67. _logfire_sdk/logfire/_internal/integrations/claude_agent_sdk.py +628 -0
  68. _logfire_sdk/logfire/_internal/integrations/django.py +41 -0
  69. _logfire_sdk/logfire/_internal/integrations/dspy.py +20 -0
  70. _logfire_sdk/logfire/_internal/integrations/executors.py +99 -0
  71. _logfire_sdk/logfire/_internal/integrations/fastapi.py +421 -0
  72. _logfire_sdk/logfire/_internal/integrations/flask.py +53 -0
  73. _logfire_sdk/logfire/_internal/integrations/google_genai.py +66 -0
  74. _logfire_sdk/logfire/_internal/integrations/httpx.py +577 -0
  75. _logfire_sdk/logfire/_internal/integrations/litellm.py +20 -0
  76. _logfire_sdk/logfire/_internal/integrations/litestar.py +77 -0
  77. _logfire_sdk/logfire/_internal/integrations/llm_providers/anthropic.py +406 -0
  78. _logfire_sdk/logfire/_internal/integrations/llm_providers/llm_provider.py +251 -0
  79. _logfire_sdk/logfire/_internal/integrations/llm_providers/openai.py +892 -0
  80. _logfire_sdk/logfire/_internal/integrations/llm_providers/semconv.py +194 -0
  81. _logfire_sdk/logfire/_internal/integrations/llm_providers/types.py +36 -0
  82. _logfire_sdk/logfire/_internal/integrations/llm_providers/usage.py +89 -0
  83. _logfire_sdk/logfire/_internal/integrations/mcp.py +191 -0
  84. _logfire_sdk/logfire/_internal/integrations/monty.py +155 -0
  85. _logfire_sdk/logfire/_internal/integrations/mysql.py +34 -0
  86. _logfire_sdk/logfire/_internal/integrations/openai_agents.py +460 -0
  87. _logfire_sdk/logfire/_internal/integrations/print.py +176 -0
  88. _logfire_sdk/logfire/_internal/integrations/psycopg.py +126 -0
  89. _logfire_sdk/logfire/_internal/integrations/pydantic_ai.py +65 -0
  90. _logfire_sdk/logfire/_internal/integrations/pymongo.py +40 -0
  91. _logfire_sdk/logfire/_internal/integrations/pytest.py +648 -0
  92. _logfire_sdk/logfire/_internal/integrations/redis.py +57 -0
  93. _logfire_sdk/logfire/_internal/integrations/requests.py +34 -0
  94. _logfire_sdk/logfire/_internal/integrations/snowflake.py +162 -0
  95. _logfire_sdk/logfire/_internal/integrations/sqlalchemy.py +70 -0
  96. _logfire_sdk/logfire/_internal/integrations/sqlite3.py +29 -0
  97. _logfire_sdk/logfire/_internal/integrations/starlette.py +50 -0
  98. _logfire_sdk/logfire/_internal/integrations/surrealdb.py +137 -0
  99. _logfire_sdk/logfire/_internal/integrations/system_metrics.py +322 -0
  100. _logfire_sdk/logfire/_internal/integrations/wsgi.py +34 -0
  101. _logfire_sdk/logfire/_internal/interactive.py +115 -0
  102. _logfire_sdk/logfire/_internal/json_encoder.py +344 -0
  103. _logfire_sdk/logfire/_internal/json_formatter.py +350 -0
  104. _logfire_sdk/logfire/_internal/json_schema.py +455 -0
  105. _logfire_sdk/logfire/_internal/json_types.py +147 -0
  106. _logfire_sdk/logfire/_internal/logs.py +142 -0
  107. _logfire_sdk/logfire/_internal/main.py +3498 -0
  108. _logfire_sdk/logfire/_internal/metrics.py +283 -0
  109. _logfire_sdk/logfire/_internal/scrubbing.py +404 -0
  110. _logfire_sdk/logfire/_internal/server_response.py +44 -0
  111. _logfire_sdk/logfire/_internal/stack_info.py +147 -0
  112. _logfire_sdk/logfire/_internal/tracer.py +538 -0
  113. _logfire_sdk/logfire/_internal/ulid.py +40 -0
  114. _logfire_sdk/logfire/_internal/utils.py +550 -0
  115. _logfire_sdk/logfire/cli.py +3 -0
  116. _logfire_sdk/logfire/db_api.py +393 -0
  117. _logfire_sdk/logfire/exceptions.py +9 -0
  118. _logfire_sdk/logfire/experimental/__init__.py +0 -0
  119. _logfire_sdk/logfire/experimental/annotations.py +80 -0
  120. _logfire_sdk/logfire/experimental/api_client.py +1421 -0
  121. _logfire_sdk/logfire/integrations/__init__.py +4 -0
  122. _logfire_sdk/logfire/integrations/aiohttp_client.py +12 -0
  123. _logfire_sdk/logfire/integrations/flask.py +26 -0
  124. _logfire_sdk/logfire/integrations/httpx.py +49 -0
  125. _logfire_sdk/logfire/integrations/logging.py +153 -0
  126. _logfire_sdk/logfire/integrations/loguru.py +98 -0
  127. _logfire_sdk/logfire/integrations/psycopg.py +23 -0
  128. _logfire_sdk/logfire/integrations/pydantic.py +541 -0
  129. _logfire_sdk/logfire/integrations/redis.py +31 -0
  130. _logfire_sdk/logfire/integrations/sqlalchemy.py +12 -0
  131. _logfire_sdk/logfire/integrations/structlog.py +55 -0
  132. _logfire_sdk/logfire/integrations/wsgi.py +15 -0
  133. _logfire_sdk/logfire/propagate.py +161 -0
  134. _logfire_sdk/logfire/py.typed +0 -0
  135. _logfire_sdk/logfire/query_client.py +701 -0
  136. _logfire_sdk/logfire/sampling/__init__.py +9 -0
  137. _logfire_sdk/logfire/sampling/_tail_sampling.py +292 -0
  138. _logfire_sdk/logfire/testing.py +127 -0
  139. _logfire_sdk/logfire/types.py +303 -0
  140. _logfire_sdk/logfire/variables/__init__.py +154 -0
  141. _logfire_sdk/logfire/variables/_handlebars.py +77 -0
  142. _logfire_sdk/logfire/variables/abstract.py +2027 -0
  143. _logfire_sdk/logfire/variables/composition.py +430 -0
  144. _logfire_sdk/logfire/variables/config.py +694 -0
  145. _logfire_sdk/logfire/variables/local.py +134 -0
  146. _logfire_sdk/logfire/variables/remote.py +877 -0
  147. _logfire_sdk/logfire/variables/template_validation.py +208 -0
  148. _logfire_sdk/logfire/variables/variable.py +1299 -0
  149. _logfire_sdk/logfire/version.py +5 -0
  150. logfire/.agents/skills/logfire-evals/SKILL.md +170 -0
  151. logfire/.agents/skills/logfire-gateway/SKILL.md +156 -0
  152. logfire/.agents/skills/logfire-infrastructure/SKILL.md +61 -0
  153. logfire/.agents/skills/logfire-infrastructure/references/collector/host-and-infra-metrics.md +229 -0
  154. logfire/.agents/skills/logfire-instrumentation/SKILL.md +292 -0
  155. logfire/.agents/skills/logfire-instrumentation/references/auth.md +100 -0
  156. logfire/.agents/skills/logfire-instrumentation/references/javascript/ai-sdk.md +145 -0
  157. logfire/.agents/skills/logfire-instrumentation/references/javascript/cloudflare-and-deno.md +99 -0
  158. logfire/.agents/skills/logfire-instrumentation/references/javascript/frameworks.md +22 -0
  159. logfire/.agents/skills/logfire-instrumentation/references/javascript/installation-and-env.md +75 -0
  160. logfire/.agents/skills/logfire-instrumentation/references/javascript/nextjs.md +78 -0
  161. logfire/.agents/skills/logfire-instrumentation/references/javascript/node-runtime.md +132 -0
  162. logfire/.agents/skills/logfire-instrumentation/references/javascript/patterns.md +184 -0
  163. logfire/.agents/skills/logfire-instrumentation/references/javascript/project-detection.md +43 -0
  164. logfire/.agents/skills/logfire-instrumentation/references/javascript/react-browser.md +18 -0
  165. logfire/.agents/skills/logfire-instrumentation/references/javascript/verification-troubleshooting.md +68 -0
  166. logfire/.agents/skills/logfire-instrumentation/references/python/integrations.md +104 -0
  167. logfire/.agents/skills/logfire-instrumentation/references/python/logging-patterns.md +120 -0
  168. logfire/.agents/skills/logfire-instrumentation/references/rust/patterns.md +113 -0
  169. logfire/.agents/skills/logfire-setup/SKILL.md +58 -0
  170. logfire/.agents/skills/logfire-setup-offline.md +715 -0
  171. logfire/__init__.py +226 -0
  172. logfire/__main__.py +6 -0
  173. logfire/_internal/__init__.py +14 -0
  174. logfire/_internal/ast_utils.py +264 -0
  175. logfire/_internal/async_.py +125 -0
  176. logfire/_internal/auth.py +298 -0
  177. logfire/_internal/auto_trace/__init__.py +74 -0
  178. logfire/_internal/auto_trace/import_hook.py +137 -0
  179. logfire/_internal/auto_trace/rewrite_ast.py +185 -0
  180. logfire/_internal/auto_trace/types.py +44 -0
  181. logfire/_internal/baggage.py +109 -0
  182. logfire/_internal/cli/__init__.py +1081 -0
  183. logfire/_internal/cli/ai_tools.py +231 -0
  184. logfire/_internal/cli/auth.py +151 -0
  185. logfire/_internal/cli/gateway.py +627 -0
  186. logfire/_internal/cli/gateway_auth.py +313 -0
  187. logfire/_internal/cli/prompt.py +50 -0
  188. logfire/_internal/cli/run.py +590 -0
  189. logfire/_internal/client.py +178 -0
  190. logfire/_internal/collect_system_info.py +29 -0
  191. logfire/_internal/config.py +2471 -0
  192. logfire/_internal/config_params.py +343 -0
  193. logfire/_internal/constants.py +185 -0
  194. logfire/_internal/db_statement_summary.py +140 -0
  195. logfire/_internal/exporters/__init__.py +1 -0
  196. logfire/_internal/exporters/console.py +517 -0
  197. logfire/_internal/exporters/dynamic_batch.py +49 -0
  198. logfire/_internal/exporters/logs.py +30 -0
  199. logfire/_internal/exporters/otlp.py +517 -0
  200. logfire/_internal/exporters/processor_wrapper.py +652 -0
  201. logfire/_internal/exporters/quiet_metrics.py +18 -0
  202. logfire/_internal/exporters/remove_pending.py +45 -0
  203. logfire/_internal/exporters/test.py +257 -0
  204. logfire/_internal/exporters/wrapper.py +106 -0
  205. logfire/_internal/formatter.py +379 -0
  206. logfire/_internal/forwarding.py +585 -0
  207. logfire/_internal/http_transport.py +193 -0
  208. logfire/_internal/instrument.py +254 -0
  209. logfire/_internal/integrations/__init__.py +1 -0
  210. logfire/_internal/integrations/aiohttp_client.py +324 -0
  211. logfire/_internal/integrations/aiohttp_server.py +22 -0
  212. logfire/_internal/integrations/asgi.py +117 -0
  213. logfire/_internal/integrations/asyncpg.py +21 -0
  214. logfire/_internal/integrations/aws_lambda.py +36 -0
  215. logfire/_internal/integrations/celery.py +20 -0
  216. logfire/_internal/integrations/claude_agent_sdk.py +628 -0
  217. logfire/_internal/integrations/django.py +41 -0
  218. logfire/_internal/integrations/dspy.py +20 -0
  219. logfire/_internal/integrations/executors.py +99 -0
  220. logfire/_internal/integrations/fastapi.py +421 -0
  221. logfire/_internal/integrations/flask.py +53 -0
  222. logfire/_internal/integrations/google_genai.py +66 -0
  223. logfire/_internal/integrations/httpx.py +577 -0
  224. logfire/_internal/integrations/litellm.py +20 -0
  225. logfire/_internal/integrations/litestar.py +77 -0
  226. logfire/_internal/integrations/llm_providers/anthropic.py +406 -0
  227. logfire/_internal/integrations/llm_providers/llm_provider.py +251 -0
  228. logfire/_internal/integrations/llm_providers/openai.py +892 -0
  229. logfire/_internal/integrations/llm_providers/semconv.py +194 -0
  230. logfire/_internal/integrations/llm_providers/types.py +36 -0
  231. logfire/_internal/integrations/llm_providers/usage.py +89 -0
  232. logfire/_internal/integrations/mcp.py +191 -0
  233. logfire/_internal/integrations/monty.py +155 -0
  234. logfire/_internal/integrations/mysql.py +34 -0
  235. logfire/_internal/integrations/openai_agents.py +460 -0
  236. logfire/_internal/integrations/print.py +176 -0
  237. logfire/_internal/integrations/psycopg.py +126 -0
  238. logfire/_internal/integrations/pydantic_ai.py +65 -0
  239. logfire/_internal/integrations/pymongo.py +40 -0
  240. logfire/_internal/integrations/pytest.py +648 -0
  241. logfire/_internal/integrations/redis.py +57 -0
  242. logfire/_internal/integrations/requests.py +34 -0
  243. logfire/_internal/integrations/snowflake.py +162 -0
  244. logfire/_internal/integrations/sqlalchemy.py +70 -0
  245. logfire/_internal/integrations/sqlite3.py +29 -0
  246. logfire/_internal/integrations/starlette.py +50 -0
  247. logfire/_internal/integrations/surrealdb.py +137 -0
  248. logfire/_internal/integrations/system_metrics.py +322 -0
  249. logfire/_internal/integrations/wsgi.py +34 -0
  250. logfire/_internal/interactive.py +115 -0
  251. logfire/_internal/json_encoder.py +344 -0
  252. logfire/_internal/json_formatter.py +350 -0
  253. logfire/_internal/json_schema.py +455 -0
  254. logfire/_internal/json_types.py +147 -0
  255. logfire/_internal/logs.py +142 -0
  256. logfire/_internal/main.py +3498 -0
  257. logfire/_internal/metrics.py +283 -0
  258. logfire/_internal/scrubbing.py +404 -0
  259. logfire/_internal/server_response.py +44 -0
  260. logfire/_internal/stack_info.py +147 -0
  261. logfire/_internal/tracer.py +538 -0
  262. logfire/_internal/ulid.py +40 -0
  263. logfire/_internal/utils.py +550 -0
  264. logfire/cli.py +3 -0
  265. logfire/db_api.py +393 -0
  266. logfire/exceptions.py +9 -0
  267. logfire/experimental/__init__.py +0 -0
  268. logfire/experimental/annotations.py +80 -0
  269. logfire/experimental/api_client.py +1421 -0
  270. logfire/integrations/__init__.py +4 -0
  271. logfire/integrations/aiohttp_client.py +12 -0
  272. logfire/integrations/flask.py +26 -0
  273. logfire/integrations/httpx.py +49 -0
  274. logfire/integrations/logging.py +153 -0
  275. logfire/integrations/loguru.py +98 -0
  276. logfire/integrations/psycopg.py +23 -0
  277. logfire/integrations/pydantic.py +541 -0
  278. logfire/integrations/redis.py +31 -0
  279. logfire/integrations/sqlalchemy.py +12 -0
  280. logfire/integrations/structlog.py +55 -0
  281. logfire/integrations/wsgi.py +15 -0
  282. logfire/propagate.py +161 -0
  283. logfire/py.typed +0 -0
  284. logfire/query_client.py +701 -0
  285. logfire/sampling/__init__.py +9 -0
  286. logfire/sampling/_tail_sampling.py +292 -0
  287. logfire/testing.py +127 -0
  288. logfire/types.py +303 -0
  289. logfire/variables/__init__.py +154 -0
  290. logfire/variables/_handlebars.py +77 -0
  291. logfire/variables/abstract.py +2027 -0
  292. logfire/variables/composition.py +430 -0
  293. logfire/variables/config.py +694 -0
  294. logfire/variables/local.py +134 -0
  295. logfire/variables/remote.py +877 -0
  296. logfire/variables/template_validation.py +208 -0
  297. logfire/variables/variable.py +1299 -0
  298. logfire/version.py +5 -0
  299. logfire_sdk-5.3.0.dist-info/METADATA +140 -0
  300. logfire_sdk-5.3.0.dist-info/RECORD +304 -0
  301. logfire_sdk-5.3.0.dist-info/WHEEL +4 -0
  302. logfire_sdk-5.3.0.dist-info/entry_points.txt +6 -0
  303. logfire_sdk-5.3.0.dist-info/licenses/LICENSE +21 -0
  304. logfire_sdk.pth +2 -0
@@ -0,0 +1,22 @@
1
+ # JavaScript Framework Setup
2
+
3
+ This file is a compatibility index for older prompts that ask for the JS framework reference directly. For new instrumentation work, read [project-detection.md](./project-detection.md) first, then the runtime-specific reference.
4
+
5
+ ## Runtime Routing
6
+
7
+ | Detected project | Primary reference | Runtime package |
8
+ | --- | --- | --- |
9
+ | Express, Fastify, Koa, Hono on Node, scripts, CLIs, workers outside edge runtimes | [node-runtime.md](./node-runtime.md) | `@pydantic/logfire-node` |
10
+ | Next.js server-side tracing | [nextjs.md](./nextjs.md) | `@vercel/otel` plus `logfire` for manual spans |
11
+ | React/Vite/browser tracing | [react-browser.md](./react-browser.md) | `@pydantic/logfire-browser` |
12
+ | Cloudflare Workers | [cloudflare-and-deno.md](./cloudflare-and-deno.md) | `@pydantic/logfire-cf-workers` plus `logfire` |
13
+ | Deno | [cloudflare-and-deno.md](./cloudflare-and-deno.md) | Deno OpenTelemetry plus `npm:logfire` |
14
+ | Vercel AI SDK | [ai-sdk.md](./ai-sdk.md) | Depends on Node or Next.js setup |
15
+
16
+ ## Current Defaults
17
+
18
+ - Use `node --import ./instrumentation.js` for modern Node ESM preload. Use `--require` only for CommonJS.
19
+ - Browser code sends directly with a restricted public frontend application token and its regional base URL through `configureFrontend({ baseUrl, token })` (`@pydantic/logfire-browser` 0.21.0 or later). Never expose `LOGFIRE_TOKEN`, `OTEL_EXPORTER_OTLP_HEADERS`, or another ordinary write token in a browser bundle.
20
+ - Single-page applications should set `rum.session.getRouteName`. With `@pydantic/logfire-browser` 0.28.0 or later, use the React Router, TanStack Router, or Vue Router helper described in [react-browser.md](./react-browser.md#group-pages-by-route).
21
+ - Next.js server-side tracing should use `@vercel/otel`; do not use `@pydantic/logfire-node` as the primary Next server setup unless the app has a separate custom Node server.
22
+ - Cloudflare Workers wrap the exported handler with `instrument()` from `@pydantic/logfire-cf-workers`; import manual spans/logs from `logfire`.
@@ -0,0 +1,75 @@
1
+ # JavaScript / TypeScript Installation And Environment
2
+
3
+ Use the package manager detected in [project-detection.md](./project-detection.md). Install packages in the package or workspace that owns the runtime.
4
+
5
+ ## Package Matrix
6
+
7
+ | Runtime | Install |
8
+ | --- | --- |
9
+ | Node.js server, worker, CLI, script | `@pydantic/logfire-node @opentelemetry/auto-instrumentations-node` |
10
+ | Next.js server-side tracing | `@vercel/otel logfire` |
11
+ | Browser/React/Vite client tracing | `@pydantic/logfire-browser` |
12
+ | Cloudflare Workers in-process tracing | `@pydantic/logfire-cf-workers logfire` |
13
+ | Deno | usually no package install; import `npm:logfire` for manual spans |
14
+ | Vercel AI SDK | no Logfire-specific package beyond the runtime setup; ensure `ai` telemetry is enabled in calls |
15
+
16
+ `@pydantic/logfire-node` expects OpenTelemetry packages as peers. If the package manager reports unmet `@opentelemetry/*` peers, install the reported packages rather than suppressing the warning.
17
+
18
+ ## Environment Variables
19
+
20
+ Node.js and Cloudflare read Logfire-specific environment values. `LOGFIRE_TOKEN` is optional for local Node.js development specifically: `@pydantic/logfire-node` falls back to `.logfire/logfire_credentials.json` when it's unset, same as the Python SDK. Cloudflare has no equivalent fallback (see [cloudflare-and-deno.md](./cloudflare-and-deno.md)), so set it explicitly there always; for Node.js, set it explicitly only to override the local one — a different token, or production, where it should be a separately-minted token per [auth.md](../auth.md)'s "If the calling skill needs a write token" section.
21
+
22
+ ```bash
23
+ LOGFIRE_TOKEN=your-write-token
24
+ LOGFIRE_SERVICE_NAME=checkout-api
25
+ LOGFIRE_SERVICE_VERSION=1.0.0
26
+ LOGFIRE_ENVIRONMENT=development
27
+ ```
28
+
29
+ Node.js also supports:
30
+
31
+ ```bash
32
+ LOGFIRE_CONSOLE=true
33
+ LOGFIRE_MIN_LEVEL=info
34
+ LOGFIRE_SEND_TO_LOGFIRE=if-token-present
35
+ LOGFIRE_TRACE_SAMPLE_RATE=0.1
36
+ LOGFIRE_BASE_URL=https://logfire-api.pydantic.dev
37
+ ```
38
+
39
+ Next.js, Deno, and other platform OpenTelemetry integrations use OTLP variables:
40
+
41
+ ```bash
42
+ OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-api.pydantic.dev
43
+ OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'
44
+ ```
45
+
46
+ Use endpoint-specific variables when the platform requires them:
47
+
48
+ ```bash
49
+ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
50
+ OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://logfire-api.pydantic.dev/v1/metrics
51
+ ```
52
+
53
+ ## Secret Placement
54
+
55
+ - Put `LOGFIRE_TOKEN` in server-only env files, deployment secrets, or Worker secrets.
56
+ - Do not create `NEXT_PUBLIC_LOGFIRE_TOKEN`, `VITE_LOGFIRE_TOKEN`, `PUBLIC_LOGFIRE_TOKEN`, or any public write-token variable.
57
+ - For browser code, create a frontend application and pass its regional base URL and restricted public token to `configureFrontend({ baseUrl, token })` (`@pydantic/logfire-browser` 0.21.0 or later). Never reuse `LOGFIRE_TOKEN` or another ordinary write token in the browser.
58
+ - A frontend application token is intentionally restricted and public. Embed the generated token and regional base URL directly in the client bundle, or supply them through the app's public build/runtime configuration (for example, `VITE_LOGFIRE_FRONTEND_TOKEN` and `VITE_LOGFIRE_BASE_URL`). Do not deploy the generated example with placeholder values.
59
+ - Preserve an existing backend telemetry proxy. Add a new one only when the application needs its own authentication, origin checks, or rate limits; hiding the restricted token alone is not a reason.
60
+ - Update `.env.example` or documented env templates with placeholder values, not real tokens.
61
+ - If the app has separate frontend and backend packages, put the write token only in the backend package or hosting environment.
62
+
63
+ ## Service Metadata
64
+
65
+ Set stable service names. Prefer deployable-unit names:
66
+
67
+ ```ts
68
+ logfire.configure({
69
+ serviceName: 'checkout-api',
70
+ serviceVersion: process.env.npm_package_version,
71
+ environment: process.env.NODE_ENV,
72
+ })
73
+ ```
74
+
75
+ For browser telemetry, the frontend application pins the service name, namespace, and optional environment. Do not override them in browser SDK configuration. For Next.js, keep the server service name distinct from the frontend application name.
@@ -0,0 +1,78 @@
1
+ # Next.js Instrumentation
2
+
3
+ Use this for Next.js apps. Instrument server-side Next telemetry separately from optional browser tracing.
4
+
5
+ ## Server-Side Tracing
6
+
7
+ Install in the Next.js app package:
8
+
9
+ ```bash
10
+ npm install @vercel/otel logfire
11
+ ```
12
+
13
+ Create `instrumentation.ts` in the project root, or `src/instrumentation.ts` if the app uses `src`:
14
+
15
+ ```ts
16
+ import { registerOTel } from '@vercel/otel'
17
+
18
+ export function register() {
19
+ registerOTel({
20
+ serviceName: process.env.LOGFIRE_SERVICE_NAME ?? 'nextjs-app',
21
+ })
22
+ }
23
+ ```
24
+
25
+ Set server-only env vars in `.env.local`, deployment secrets, or the hosting dashboard:
26
+
27
+ ```bash
28
+ OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-api.pydantic.dev
29
+ OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'
30
+ LOGFIRE_SERVICE_NAME=nextjs-app
31
+ ```
32
+
33
+ Do not prefix write-token variables with `NEXT_PUBLIC_`.
34
+
35
+ ## Manual Server Spans
36
+
37
+ Use the runtime-agnostic `logfire` package in server components, route handlers, server actions, and other server-only code:
38
+
39
+ ```tsx
40
+ import * as logfire from 'logfire'
41
+
42
+ export default async function Page() {
43
+ return logfire.span('render home page', {
44
+ callback: async () => {
45
+ logfire.info('loading homepage data')
46
+ return <main>Hello</main>
47
+ },
48
+ })
49
+ }
50
+ ```
51
+
52
+ Route handler error reporting:
53
+
54
+ ```ts
55
+ import * as logfire from 'logfire'
56
+
57
+ export async function POST(request: Request) {
58
+ try {
59
+ return Response.json(await createOrder(await request.json()))
60
+ } catch (error) {
61
+ logfire.reportError('create order route failed', error)
62
+ throw error
63
+ }
64
+ }
65
+ ```
66
+
67
+ ## Client-Side Browser Tracing
68
+
69
+ Use the [frontend specialist](https://pydantic.dev/.well-known/agent-skills/logfire-frontend/SKILL.md)
70
+ for client initialization, route grouping, capture policy, and replay. Browser
71
+ setup needs its restricted frontend application token, not this server's write
72
+ token. Keep browser and server telemetry separate.
73
+
74
+ ## Vercel Deployment Notes
75
+
76
+ - Add server OTLP and ordinary Logfire token values to the Vercel project environment. Supply the separate frontend application configuration through the app's existing public runtime-config mechanism.
77
+ - If spans do not appear after changing tracing env vars, clear the Vercel data cache for the project and redeploy.
78
+ - Confirm server and browser data appear as distinct services; the frontend application's identity owns the browser service name.
@@ -0,0 +1,132 @@
1
+ # Node.js Runtime Instrumentation
2
+
3
+ Use this for Express, Fastify, Koa, Hono on Node, background workers, CLIs, and scripts. For Next.js without a custom server, use [nextjs.md](./nextjs.md) instead.
4
+
5
+ ## Install
6
+
7
+ Install in the app package:
8
+
9
+ ```bash
10
+ npm install @pydantic/logfire-node @opentelemetry/auto-instrumentations-node
11
+ ```
12
+
13
+ Use the repo's package manager. If peer dependency warnings name additional `@opentelemetry/*` packages, install the reported peers.
14
+
15
+ ## Instrumentation File
16
+
17
+ Create an instrumentation module that is loaded before the app imports instrumented libraries:
18
+
19
+ ```ts
20
+ // instrumentation.ts
21
+ import 'dotenv/config'
22
+ import * as logfire from '@pydantic/logfire-node'
23
+
24
+ logfire.configure({
25
+ serviceName: process.env.LOGFIRE_SERVICE_NAME ?? 'node-service',
26
+ serviceVersion: process.env.npm_package_version,
27
+ environment: process.env.NODE_ENV,
28
+ })
29
+ ```
30
+
31
+ For local debugging, add `console: true` or set `LOGFIRE_CONSOLE=true`.
32
+
33
+ ## Startup Scripts
34
+
35
+ Preserve the existing runner and add a preload.
36
+
37
+ ESM or modern Node:
38
+
39
+ ```json
40
+ {
41
+ "scripts": {
42
+ "start": "node --import ./dist/instrumentation.js ./dist/server.js"
43
+ }
44
+ }
45
+ ```
46
+
47
+ TypeScript during development with `tsx`:
48
+
49
+ ```json
50
+ {
51
+ "scripts": {
52
+ "dev": "node --import tsx --import ./src/instrumentation.ts ./src/server.ts"
53
+ }
54
+ }
55
+ ```
56
+
57
+ CommonJS:
58
+
59
+ ```js
60
+ // instrumentation.cjs
61
+ require('dotenv/config')
62
+ const logfire = require('@pydantic/logfire-node')
63
+
64
+ logfire.configure({ serviceName: process.env.LOGFIRE_SERVICE_NAME || 'node-service' })
65
+ ```
66
+
67
+ ```json
68
+ {
69
+ "scripts": {
70
+ "start": "node --require ./instrumentation.cjs ./server.cjs"
71
+ }
72
+ }
73
+ ```
74
+
75
+ Use `--require` only for CommonJS. Prefer `--import` for ESM and modern Node apps.
76
+
77
+ ## Manual Spans In App Code
78
+
79
+ After the preload configures the SDK, app modules can import the same package for manual spans:
80
+
81
+ ```ts
82
+ import * as logfire from '@pydantic/logfire-node'
83
+
84
+ app.get('/orders/:id', async (req, res) => {
85
+ const order = await logfire.span('load order {order_id}', {
86
+ attributes: { order_id: req.params.id },
87
+ callback: async () => loadOrder(req.params.id),
88
+ })
89
+
90
+ res.json(order)
91
+ })
92
+ ```
93
+
94
+ Express error handler:
95
+
96
+ ```ts
97
+ app.use((err: Error, req: express.Request, res: express.Response, _next: express.NextFunction) => {
98
+ logfire.reportError('express request failed', err, { path: req.path }, { tags: ['express'] })
99
+ res.status(500).send('internal server error')
100
+ })
101
+ ```
102
+
103
+ ## Auto-Instrumentation Configuration
104
+
105
+ Disable noisy or unsafe instrumentations in `configure()`:
106
+
107
+ ```ts
108
+ logfire.configure({
109
+ serviceName: 'checkout-api',
110
+ nodeAutoInstrumentations: {
111
+ '@opentelemetry/instrumentation-fs': { enabled: false },
112
+ '@opentelemetry/instrumentation-http': { enabled: true },
113
+ },
114
+ })
115
+ ```
116
+
117
+ Do not import Express, HTTP clients, database clients, or other instrumented libraries before this file is loaded.
118
+
119
+ ## Scripts And CLIs
120
+
121
+ Short-lived processes should explicitly shut down:
122
+
123
+ ```ts
124
+ try {
125
+ await runJob()
126
+ logfire.info('job finished')
127
+ } finally {
128
+ await logfire.shutdown({ timeoutMillis: 5000 })
129
+ }
130
+ ```
131
+
132
+ Use `forceFlush()` when the process continues but queued telemetry needs to be exported immediately.
@@ -0,0 +1,184 @@
1
+ # JavaScript / TypeScript Manual API Patterns
2
+
3
+ Use this reference when adding manual spans, logs, function wrappers, error reporting, tags, baggage projection, sampling, or scrubbing to JS/TS code.
4
+
5
+ ## Imports
6
+
7
+ Use the runtime package when it configures the SDK and re-exports the manual API. Choose the package that matches the runtime; do not copy both imports into one file.
8
+
9
+ ```ts
10
+ import * as logfire from '@pydantic/logfire-node'
11
+ ```
12
+
13
+ ```ts
14
+ import * as logfire from '@pydantic/logfire-browser'
15
+ ```
16
+
17
+ Use `logfire` directly when OpenTelemetry is configured by the platform or another runtime package:
18
+
19
+ ```ts
20
+ import * as logfire from 'logfire'
21
+ ```
22
+
23
+ Cloudflare Workers use both imports when they need handler wrapping and manual spans:
24
+
25
+ ```ts
26
+ import * as logfire from 'logfire'
27
+ import { instrument } from '@pydantic/logfire-cf-workers'
28
+ ```
29
+
30
+ ## Logs
31
+
32
+ Log helpers create point-in-time Logfire events. The second argument is structured attributes; use it for anything the user should be able to search or query.
33
+
34
+ ```ts
35
+ logfire.trace('cache lookup {cache_key}', { cache_key })
36
+ logfire.debug('provider response received', { provider, status })
37
+ logfire.info('order created {order_id}', { order_id })
38
+ logfire.notice('plan upgraded {tenant}', { tenant })
39
+ logfire.warning('retrying provider call', { provider, attempt })
40
+ logfire.error('payment failed', { payment_id, provider })
41
+ logfire.fatal('worker cannot start', { service: 'billing-worker' })
42
+ ```
43
+
44
+ Do not flatten useful attributes into interpolated strings:
45
+
46
+ ```ts
47
+ // Avoid
48
+ logfire.info(`order created ${orderId}`)
49
+
50
+ // Prefer
51
+ logfire.info('order created {order_id}', { order_id: orderId })
52
+ ```
53
+
54
+ ## Spans
55
+
56
+ Prefer the current options-object form. `span()` auto-closes after the callback resolves or throws, records thrown errors on the span, and preserves the callback result.
57
+
58
+ ```ts
59
+ await logfire.span('process order {order_id}', {
60
+ attributes: { order_id: orderId },
61
+ callback: async () => {
62
+ const items = await fetchItems(orderId)
63
+ logfire.info('fetched order items', { count: items.length })
64
+ return processItems(items)
65
+ },
66
+ })
67
+ ```
68
+
69
+ Use `startSpan()` only when the lifetime cannot be expressed as a callback:
70
+
71
+ ```ts
72
+ const span = logfire.startSpan('run job {job_id}', { job_id: jobId })
73
+ try {
74
+ await runJob(jobId)
75
+ } finally {
76
+ span.end()
77
+ }
78
+ ```
79
+
80
+ Use `startPendingSpan()` for long-running operations that should appear in Logfire immediately:
81
+
82
+ ```ts
83
+ const span = logfire.startPendingSpan('load dashboard', { route: '/dashboard' })
84
+ try {
85
+ await loadDashboard()
86
+ } finally {
87
+ span.end()
88
+ }
89
+ ```
90
+
91
+ Pass `parentSpan` only when explicit parentage is required outside normal async context propagation.
92
+
93
+ ## Function Instrumentation
94
+
95
+ Use `instrument(fn, options)` when wrapping a reusable function is cleaner than editing its body.
96
+
97
+ ```ts
98
+ const fetchCustomer = logfire.instrument(fetchCustomerImpl, {
99
+ message: 'fetch customer {customer_id}',
100
+ extractArgs: ['customer_id'],
101
+ tags: ['customers'],
102
+ })
103
+
104
+ await fetchCustomer('cus_123')
105
+ ```
106
+
107
+ Prefer explicit `extractArgs: ['name']`. Avoid `extractArgs: true` in production code that may be bundled or minified. Use `recordReturn: true` sparingly and only for non-sensitive, bounded values.
108
+
109
+ ## Errors
110
+
111
+ Use `reportError()` from explicit catch blocks. The caught value can be `unknown`.
112
+
113
+ ```ts
114
+ try {
115
+ await syncCustomer(customerId)
116
+ } catch (error) {
117
+ logfire.reportError('customer sync failed', error, { customer_id: customerId }, { tags: ['customers'] })
118
+ throw error
119
+ }
120
+ ```
121
+
122
+ `reportError()` is the JavaScript API; there is no Python-style `exception()` helper.
123
+
124
+ ## Scoped Clients And Tags
125
+
126
+ Use `withTags()` or `withSettings()` when several calls share stable defaults.
127
+
128
+ ```ts
129
+ const payments = logfire.withTags('payments')
130
+
131
+ payments.info('payment authorized {payment_id}', { payment_id })
132
+
133
+ await payments.span('capture payment {payment_id}', {
134
+ attributes: { payment_id },
135
+ callback: async () => capturePayment(paymentId),
136
+ })
137
+ ```
138
+
139
+ Per-call tags are merged with scoped tags. Tags should identify stable subsystems or workflows, not high-cardinality user data.
140
+
141
+ ## Configuration Options
142
+
143
+ Runtime `configure()` calls accept common manual API options such as `minLevel`, `baggage`, `jsonSchema`, `scrubbing`, and `sampling`.
144
+
145
+ ```ts
146
+ logfire.configure({
147
+ serviceName: 'checkout-api',
148
+ environment: process.env.NODE_ENV,
149
+ minLevel: 'info',
150
+ scrubbing: {
151
+ extraPatterns: ['secret_token'],
152
+ },
153
+ baggage: {
154
+ spanAttributes: ['tenant', 'region'],
155
+ },
156
+ })
157
+ ```
158
+
159
+ Keep baggage allowlists small and stable. Do not put secrets, session cookies, raw emails, or access tokens in baggage or span attributes.
160
+
161
+ ## Sampling
162
+
163
+ Use head sampling for broad volume reduction:
164
+
165
+ ```ts
166
+ logfire.configure({
167
+ serviceName: 'checkout-api',
168
+ sampling: { head: 0.1 },
169
+ })
170
+ ```
171
+
172
+ Use tail sampling when errors or slow traces must be kept:
173
+
174
+ ```ts
175
+ logfire.configure({
176
+ serviceName: 'checkout-api',
177
+ sampling: logfire.levelOrDuration({
178
+ durationThreshold: 2.0,
179
+ levelThreshold: 'warning',
180
+ }),
181
+ })
182
+ ```
183
+
184
+ Be conservative with tail sampling in browsers and long-lived processes because it buffers spans.
@@ -0,0 +1,43 @@
1
+ # JavaScript / TypeScript Project Detection
2
+
3
+ Read this before editing a JS/TS project. Instrument every runtime in the app, not just the first `package.json` you find.
4
+
5
+ ## Locate The Package Boundary
6
+
7
+ 1. Find all `package.json` files, ignoring `node_modules`, build output, generated clients, and vendored examples unless the user explicitly targets them.
8
+ 2. If the repo has workspaces, identify which workspace owns the app entrypoint. Install dependencies in that workspace.
9
+ 3. Choose the package manager from lockfiles:
10
+ - `pnpm-lock.yaml`: `pnpm add`
11
+ - `yarn.lock`: `yarn add`
12
+ - `bun.lock` or `bun.lockb`: `bun add`
13
+ - `package-lock.json`: `npm install`
14
+ - no lockfile: preserve the scripts' existing manager when obvious, otherwise use `npm install`
15
+ 4. If a package already has a Logfire or OpenTelemetry setup, extend it instead of adding a duplicate provider.
16
+
17
+ ## Detect Runtimes And Frameworks
18
+
19
+ Inspect dependencies, devDependencies, scripts, config files, and entrypoints.
20
+
21
+ | Signal | Treat as | Read |
22
+ | --- | --- | --- |
23
+ | `next`, `next.config.*`, `app/`, `pages/` | Next.js | [nextjs.md](./nextjs.md) |
24
+ | `express`, `fastify`, `koa`, Node server scripts, `src/server.*`, `src/app.*` | Node server | [node-runtime.md](./node-runtime.md) |
25
+ | `vite`, `react`, `@vitejs/*`, `src/main.tsx`, browser-only SPA | Browser app | [react-browser.md](./react-browser.md) |
26
+ | `wrangler.*`, `@cloudflare/workers-types`, scripts invoking `wrangler` | Cloudflare Workers | [cloudflare-and-deno.md](./cloudflare-and-deno.md) |
27
+ | `deno.json`, `deno.lock`, Deno task scripts | Deno | [cloudflare-and-deno.md](./cloudflare-and-deno.md) |
28
+ | `ai`, `@ai-sdk/*` | Vercel AI SDK calls | [ai-sdk.md](./ai-sdk.md) |
29
+ | Existing `@opentelemetry/*`, `@vercel/otel`, `instrumentation.ts`, `OTEL_*` env docs | Existing OTel | Extend current setup |
30
+
31
+ ## Existing OpenTelemetry Rules
32
+
33
+ - Do not create a second global tracer provider in the same runtime.
34
+ - If `@vercel/otel` is present in Next.js, add Logfire OTLP env vars and use the `logfire` package for manual spans.
35
+ - If a Node app already has a custom `NodeSDK`, add Logfire exporters/processors only if the current SDK structure is clear. Otherwise ask before replacing custom OTel wiring.
36
+ - If OpenTelemetry env vars already point to another backend, preserve them unless the user explicitly wants Logfire to replace that backend. Prefer documenting the conflict over silently changing production export destinations.
37
+
38
+ ## Entry Point Rules
39
+
40
+ - Node auto-instrumentation must be loaded before instrumented libraries are imported.
41
+ - Framework files that run in both server and browser contexts must not import `@pydantic/logfire-node` or read server secrets from client code.
42
+ - Browser instrumentation must run in browser-only modules (`'use client'`, client entrypoint, or dynamic import with SSR disabled).
43
+ - For monorepos, add one service name per deployable service, not one name for the whole repo.
@@ -0,0 +1,18 @@
1
+ # React And Browser Instrumentation
2
+
3
+ Browser errors, RUM, Web Vitals, route grouping, and session replays are owned by
4
+ the [frontend specialist](https://pydantic.dev/.well-known/agent-skills/logfire-frontend/SKILL.md).
5
+ Load that skill instead of initializing an ordinary SDK project write token.
6
+ It covers React/Vite and Next.js browser entrypoints, restricted frontend
7
+ application tokens, privacy controls, and verification.
8
+
9
+ For a Next.js server as well as its browser app, retain
10
+ [Next.js server instrumentation](./nextjs.md). Do not expand a browser-only task
11
+ to instrument a server.
12
+
13
+ ## Group Pages By Route
14
+
15
+ The frontend specialist owns router integration and route-template grouping.
16
+ Follow its browser setup reference and the browser SDK's
17
+ [route-name contract](https://pydantic.dev/docs/logfire/instrument/typescript/packages/browser/#route-names)
18
+ rather than deriving templates from raw URLs.
@@ -0,0 +1,68 @@
1
+ # JavaScript / TypeScript Verification And Troubleshooting
2
+
3
+ Run the project's normal checks and at least one runtime smoke path after instrumentation.
4
+
5
+ ## Static Checks
6
+
7
+ - Run the package's typecheck, build, lint, or test script when present.
8
+ - For monorepos, run checks for the modified workspace.
9
+ - Ensure imports match module format: ESM uses `import`, CommonJS uses `require`.
10
+ - Search client code and public env files for leaked write-token names or values.
11
+
12
+ Useful searches:
13
+
14
+ ```bash
15
+ rg "LOGFIRE_TOKEN|NEXT_PUBLIC_.*LOGFIRE|VITE_.*LOGFIRE|Authorization=.*logfire|Authorization=.*pylf"
16
+ rg "@pydantic/logfire-node" src app pages
17
+ ```
18
+
19
+ The second search should not find browser-only modules.
20
+
21
+ ## Runtime Smoke Tests
22
+
23
+ Node:
24
+
25
+ 1. Set `LOGFIRE_CONSOLE=true` and a token or `LOGFIRE_SEND_TO_LOGFIRE=false`.
26
+ 2. Start through the instrumented script.
27
+ 3. Trigger one request or job.
28
+ 4. Confirm local console output or Logfire traces.
29
+
30
+ Next.js:
31
+
32
+ 1. Confirm `instrumentation.ts` is in root or `src`.
33
+ 2. Start the app with OTLP env vars set.
34
+ 3. Load a server-rendered route or call a route handler.
35
+ 4. If browser tracing was added, inspect network requests to the `/v1/traces` URL derived from the regional `baseUrl`, or to the existing proxy URL when the app deliberately uses one.
36
+
37
+ Cloudflare:
38
+
39
+ 1. Run the existing Wrangler dev script.
40
+ 2. Trigger a Worker request.
41
+ 3. Confirm `.dev.vars` has `LOGFIRE_TOKEN` locally and production uses `wrangler secret`.
42
+
43
+ Deno:
44
+
45
+ 1. Run with `OTEL_DENO=true` and `--unstable-otel`.
46
+ 2. Trigger a manual span or request path.
47
+
48
+ ## Common Missing-Trace Causes
49
+
50
+ - Node instrumentation file is imported after Express, HTTP clients, database clients, or the app entrypoint.
51
+ - The start script was changed for `dev` but production uses a different uninstrumented script.
52
+ - The app is ESM but the preload was added as `--require` instead of `--import`.
53
+ - `LOGFIRE_TOKEN` is absent and local `.logfire` credentials are not configured.
54
+ - Browser code is using an ordinary write token instead of the restricted frontend application token, or its regional base URL and token came from different applications or regions.
55
+ - Next.js has `instrumentation.ts` in the wrong directory for the app structure.
56
+ - Vercel AI SDK 7 has no registered `@ai-sdk/otel` integration, or an AI SDK 5/6 call is missing `experimental_telemetry: { isEnabled: true }`.
57
+ - Existing OpenTelemetry configuration exports to a different backend or creates a competing tracer provider.
58
+
59
+ ## What To Report Back
60
+
61
+ Summarize:
62
+
63
+ - detected JS/TS runtimes and frameworks
64
+ - packages installed per workspace
65
+ - files changed for instrumentation and startup
66
+ - environment variables or secrets the user must set
67
+ - verification commands run and whether traces/log output were observed
68
+ - any unverified runtime path, especially production-only scripts or browser runtime configuration