Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(aio): export a trace as a json file (#124374)

Carlos Marchalae38234cde82
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 9c5d3eefb74b..766320513054 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -9770,10 +9770,18 @@ snapshots:
hash: v1.k794b7964.be74b48b9dd1bc8dc63725b475cc6de8133e6ec3a8e99a26c40e3bb7a1847c9b.KLWPm-WdZjT7u4J7EETQRamQieR3a-RxxMCWo_cl1ps
scenes-app-ai-observability-trace-view-trace-header--errored--light:
hash: v1.k794b7964.231b1a427d9e84ee1c8d77025a0369227a80ba33006fd72d8066efc86caddcaf.23SGisFFQgEXte1lfQB7ZpNH7WjAvH1CleqGu7hxGXQ
+ scenes-app-ai-observability-trace-view-trace-header--export-in-progress--dark:
+ hash: v1.k794b7964.efdf0242122a7640787ccc32dea5d3eb18a285a64564863e3014507d9c6afe88.9UDr6dhnk6vvdVquH9F8Edyqi9VYcR-efLxL4q0DJls
+ scenes-app-ai-observability-trace-view-trace-header--export-in-progress--light:
+ hash: v1.k794b7964.fab26bb7450c4f15793c92fb26e837d57d7d3ffb692357870b14623f912454a7.y5_Fe2kmCx087B2ZDBxxw5irnIFWj-nyvmnsbSAycVU
scenes-app-ai-observability-trace-view-trace-header--narrow--dark:
- hash: v1.k794b7964.27a5697d3abcb7ec0beef7c786d7a062d4cad10661f4f2b0a12fd13f18e68ca2.QFyabg8rXByyhb9o4PrGGt4mcRuHOuqEJ9zKTwGNSnE
+ hash: v1.k794b7964.15b07befce84c1e640f043985ed7100796cca9568dc2f0c743e5a44ff4f0ef8a.olwGhKEQ2CIA95Tue208-OL5Cwm-x8CIwAI8QlBWMzs
scenes-app-ai-observability-trace-view-trace-header--narrow--light:
- hash: v1.k794b7964.9fca5efe3c2de8d82b73848a8d53c57cc8beb108f927b4243c83f5e16e6814db.dlDT_i8yO4AuXDskXau5HcG0BzAI_n0LYfiX8aENnIw
+ hash: v1.k794b7964.cb8d46a7f55c0856582a1311b0e8c64adef666ac44869e5237f174ac4d6aa45a.GLFGItfsLLj9-QKMZsTX6s_I85fIsYIn8kQMNcIYbMc
+ scenes-app-ai-observability-trace-view-trace-header--with-export--dark:
+ hash: v1.k794b7964.36bc76078cc9b7c8ede2871815fd443b8ff0f6248d4e9a15c1dd92949c10b3ed.Z9IN5h7wCNsvU-DtunWxueiEY6KpNXXbgHsUGnM1FQ4
+ scenes-app-ai-observability-trace-view-trace-header--with-export--light:
+ hash: v1.k794b7964.9770434c61f3d1e6b2d2b5aa0f88abca9cb3ba0eb5166c4eb093b69d53bbe2f2.LWvtcqnui_ROvD-O4xvyuSYhlB5Oek5y1uX9qs7_hrE
scenes-app-ai-observability-trace-view-trace-header--with-search--dark:
hash: v1.k794b7964.aa0454ec525f326773af3ab8881a60f981feedb06714be27b9b44a594e0fdf42.84mnlZI9H7SWkfSDjNvp-sAYDTdT7lY2vi8RNNJFEXg
scenes-app-ai-observability-trace-view-trace-header--with-search--light:
@@ -9923,17 +9931,17 @@ snapshots:
scenes-app-ai-observability-trace-view-trace-tree--with-search-matches--light:
hash: v1.k794b7964.8371437af66a899465e8b6af209192d8faf8908b085b3ac845c286fdd571a1c0.-QUndAyEEy3bilMOkmUg1mKqV2a9wXYtwqUv6lq-zMc
scenes-app-ai-observability-trace-view-trace-view--error-trace--dark:
- hash: v1.k794b7964.a497ad504c6a9d0d425173914797467cb239bd4a2bb2cc25afb26c81eea3cdfd.1XmbemnPvJjwGHM3Jev1TAMsYMNdyx6ykWGU2d-qq2k
+ hash: v1.k794b7964.a7a017f670fee5a7a317358423030502d723c5007e4d21269b3a770ad2c41d98.asJhLo955-GX6O0pOjoZa2fe6hmagfvftM6Zg1hyPs0
scenes-app-ai-observability-trace-view-trace-view--error-trace--light:
- hash: v1.k794b7964.bf3111e7a39fc9d9c9dd2acaeb3e0a6dd264005eaf7630e02f83e76f0b31c6c4.mILO7jkQuM6lNdlXFNhncF9TyaT5CuSfze_ookKOiz4
+ hash: v1.k794b7964.e270fb50d9b25527217554014b199492777859542b04a8d042a84af8bb4f1af9.d7X6D7Ca5PURuOGuUKYZRqdTDLWoWieWf7PZatmx8mM
scenes-app-ai-observability-trace-view-trace-view--feedback-mode--dark:
- hash: v1.k794b7964.889d686dada73683048a402f1c14ba362813f9021c78dc2127a890e85d62c3a2.4W3H-CludFIrDuvCeTaRSE_lpT5WO7ZMp_rFoq69TAA
+ hash: v1.k794b7964.bb41fbe5af1874cab474d95cbd6e482dcc409f33a4d242c35067b274f8b1e825.moBcWoLtmtLN7cxIP6kBIFLNC-xJh7jcx_oRZiadn-Q
scenes-app-ai-observability-trace-view-trace-view--feedback-mode--light:
- hash: v1.k794b7964.740b5ccc6508dc0ebe7feea3a0484c54c411fe458a7e302bee274a8d107cedd3.SQNSmOiyuMYYNVPGLa7UQlPWuHETHX0X5kje6g2oP2Y
+ hash: v1.k794b7964.b746663160e505d2795ed3b5fed2a156b66ac7fa0dc1298d68d5b9db217d2bf1.bj--bzmipGXl1BVlQAdKzqy1wnR2jyKUSHwpB8qJrL0
scenes-app-ai-observability-trace-view-trace-view--generation-selected--dark:
- hash: v1.k794b7964.d31bb379f48e59e75e81826b08e59e01c8729349348209e37312494cc2f520f3.SD-1JnMC8iAmFz0cQLskows96wdUBctK7pFjw0EHCvM
+ hash: v1.k794b7964.2b838c9c5d74d37d53a38bc014fe11cda3f30c81a9f17ef606ad611559adbf47.qdaDN1liUiB-RAhjDxtSF6O_D14dZ5rXPm8HZ_znxe0
scenes-app-ai-observability-trace-view-trace-view--generation-selected--light:
- hash: v1.k794b7964.fc6b37f9158f52ff43c7142d59fee905ab0a4659407c4c4132ec3638c46f9b7a.xpXaY2gW6gZy2l7hLObvHItbSUwnaJ-D2uj3W5ZNaOs
+ hash: v1.k794b7964.98f2a3cd0f6222c771537a759a42def9863b9ef8d73fe23ec001f51a2ba802a7.8SlzXtnh-4JF3o7LK6MCNnqVMpuopxcWvHFql9K3fDQ
scenes-app-ai-observability-trace-view-trace-view--load-error--dark:
hash: v1.k794b7964.c4e963947f61276470d35e280b1b69130365cde0f3153efba7bfbab805e496de.B2FhLvOWBsI-x3axjIDbfrTFGaYKLtFR32l7sn4SCfI
scenes-app-ai-observability-trace-view-trace-view--load-error--light:
@@ -9943,17 +9951,17 @@ snapshots:
scenes-app-ai-observability-trace-view-trace-view--loading--light:
hash: v1.k794b7964.1f54d609e54318c9e0f9f1899ee8ca7bf4b0a15097de855b21c6d27806fb0025.gnPyfTsQdjTlj7UtrOYn-fH_b-Z--AipIH1rgB9In_0
scenes-app-ai-observability-trace-view-trace-view--narrow--dark:
- hash: v1.k794b7964.ddf70f48e257a7d7f6f33b72ed6c8939e860111ccd64b648feed1a4440b2a0f4.6nVI3nDwnmKLDGmdcQzpbpfsGIjJ7xMOVtRpWNzsxbU
+ hash: v1.k794b7964.0bdfbd16ff5058a5cb5e6e7cb5fb24c60d98bc7d1da087c8f0e5a6657e332f68.kQOfyJ9W0ommwX4utpmmw9VJuy-rG1xIkpLuvguWqaU
scenes-app-ai-observability-trace-view-trace-view--narrow--light:
- hash: v1.k794b7964.ebcb2b8dcfdf1792faa0f278a50789b38ce6d99ce369382a1dd5708010054268.1xy2zptkIPtDJxpuzh9tedKxmUE1AV6lsy30RtSon1k
+ hash: v1.k794b7964.a4c03d19df8e5a72720a1f57f8c91535316408ecf84efacb98014211ad4ec0aa.A62LUD6CSYHsJMZ6HdQtL3JlP9iwdCWDxKdO7iEvyJk
scenes-app-ai-observability-trace-view-trace-view--narrow-with-evals--dark:
- hash: v1.k794b7964.1ec15d0977dfc6ba6ce0244d4a128cb29e0626e8bb0a8ef68abc1133c6866923.uGAbbvbbsX8u4xKeQqFQv7rImzUP0OPv4kMslKy30aY
+ hash: v1.k794b7964.7747245cf10534fe286eedc8ae887974259f2590424d27b641c992bf2019f8b8.p7-8vtKWvsVWw3MtrmL7XlTm2XQKn5C36b_aXDnb__w
scenes-app-ai-observability-trace-view-trace-view--narrow-with-evals--light:
- hash: v1.k794b7964.6129305fc216488d475d85c4a37d01d76114c241395233fc6e34d7bedb73c7cd.hkKR3Hq1HrBBKZk0aYwMNNZYk9fKt7e5D_36eoqSXcs
+ hash: v1.k794b7964.deed35be58a19c835f77779ff3dd3a7b4377db16f08c34f5b98d8c991e81daa6.8SNGKdqWOS_EJ_cTk2P0uV27XuApGA2ytDMRv5xF1bo
scenes-app-ai-observability-trace-view-trace-view--narrow-with-search--dark:
- hash: v1.k794b7964.3b171bcede81eae28d091c8433f7dfbd6ae1a4a8ec50a404d5a9a47f683bd8c2.TcJM6FGXA5D4h78VVph1QsmAOP5nNyQXtM2PJt5bm8c
+ hash: v1.k794b7964.1a9ad3c396cd4cd85e2ccf9414ca097d584d24ab3a0c9e424b359a477b52fbd7.ECvtkMxbgMzC6EhPYXiGy3hPuWtqBJDW7quriUElzRM
scenes-app-ai-observability-trace-view-trace-view--narrow-with-search--light:
- hash: v1.k794b7964.cb6943150304640bb70cf1a3360b44711e24d9d519718d1925ad8dd5ded2ed69.VNcexyRs4WBghuIIMjyjqR4rsV1NmxYQh8tyAHZc8x4
+ hash: v1.k794b7964.335a89fc73ced2da70b9f367314ed5a04c44600c210afee3be5598680aea7f3b.5RcI8Up5p2NaMVeQOEe9B6u7A2XWjPxw12qeIfMjCfk
scenes-app-ai-observability-trace-view-trace-view--sample-anthropic-thinking-tool-use--dark:
hash: v1.k794b7964.ee72ae95c2c0db21361b7924fb3f7db28af93dae0f3773ad4530f847f95fc20c.1m0893IlRbuhUW5V-caBPubusOcO8QdDfOSfYt_iA5k
scenes-app-ai-observability-trace-view-trace-view--sample-anthropic-thinking-tool-use--light:
@@ -9971,17 +9979,17 @@ snapshots:
scenes-app-ai-observability-trace-view-trace-view--sample-open-ai-agents-with-evals--light:
hash: v1.k794b7964.0defbf16466852328781c98a0b1bad727292512e3d6ef94a34ef89a7cc7af7c8.YxnGetMJ8rP0TaFE_BGBDK33bYPoEi7QBgsYACaJnRs
scenes-app-ai-observability-trace-view-trace-view--span-selected--dark:
- hash: v1.k794b7964.d9030839e09f00adf85247243f7c3ed464c5dc92eeb24e07a236589f60f2aff5.M6PfoGn5kB0EJlPjKm5_iU-V2qMAT6e3bM_F5hX2wJI
+ hash: v1.k794b7964.2eda684b13b77907811e478364247d42f405f1a3a5a5b8b0c885da4a26ec2c8c.Y29Dsf8fflTBD9WKMRfcHJv2iIIw_tDadCpigb08wCg
scenes-app-ai-observability-trace-view-trace-view--span-selected--light:
- hash: v1.k794b7964.05f4b072801f0c443750fe53ec66bd1f7a6eefd15e1121655fa1732be4cd3c58.WKTd4i-my01kKpC88NqaEooMvQP-vhP648etK3hgGoU
+ hash: v1.k794b7964.5cb050703adb3429d626b8c13791afbc37d0c597ecc5e437413ebf1ba3c26d48.AAk8JpRWDqzxJ0P1qRHQ4uXpoin-1GpUkH3jOuFwGQw
scenes-app-ai-observability-trace-view-trace-view--thread-mode--dark:
- hash: v1.k794b7964.43cfa1c38de8c8dfb0601316dd27d9a12db42ffdc489ada0684c9809d8f9b293.oepw24gCbLpLfQjK0n9jQLFd72siJy2qGprpScEZYzY
+ hash: v1.k794b7964.c06a09c1a192d8997436eeb67ed5e9b8e096c6e50ebd5586adf753169d6773da.3WbhibXmzj1h1EhUMK9HT-RXjaoKuMiMnvpBNnO4HaU
scenes-app-ai-observability-trace-view-trace-view--thread-mode--light:
- hash: v1.k794b7964.254a76b3961b4a28cd1c15be3bc9cf8989295f9f6d9e58338bf340861b6b7fec.lTdceUiLj8nb2_4WWO2L0MwSy21HOJwI8X8PL9TGwx8
+ hash: v1.k794b7964.29eaac860520162781edf45dd9e837eff72d0ad9c06f09dbe8324cb933dcc0f5.E1YiXFqcbzLehe0E6kRY50oYceH0z4xrefFgJfUTZ6E
scenes-app-ai-observability-trace-view-trace-view--timeline-mode--dark:
- hash: v1.k794b7964.4fd30876a3d5b8cc1e4921f0b39f33bbcb4d5021bd731b5eda45a0d3c02ecfbe.z5SMZqbcY9IUJswh9a7w-CQNRFB9P8OFX4fSCbc63Hs
+ hash: v1.k794b7964.0f5cb624ec3c0c87561188fde23b2c9122baef519a827c8ba67af101028357c6.nBIRz6Sa8jFZHNY3rpINjOsVEzlMpx_dOVk7L3vDzUQ
scenes-app-ai-observability-trace-view-trace-view--timeline-mode--light:
- hash: v1.k794b7964.0a2c243cc6f5c31c0dd4816a6f8cf298b41afdafc4c448662b684d5a8db71510.AODbw-4YTpZAEfwCt2zFT8isU_e0WrbxGUXq6ukMF50
+ hash: v1.k794b7964.f32260b02fe481ec1e82b0bea5c59409638d650a38d0294ba6b9a500343bdd4f.Gjx8RyUGipWJc6o34aYnvTY4Tg0RZMPRrWWHXlKbcMU
scenes-app-ai-observability-trace-view-trace-view-switch--on-new-view--dark:
hash: v1.k794b7964.705e0647746424a98de2bbf79737ac43b3f60b57ae45b8f0e5d0cb5f01226aad.vSallcE6n-MHVAkWEOsfs2D1X--pp40NBjawl5otiOk
scenes-app-ai-observability-trace-view-trace-view-switch--on-new-view--light:
diff --git a/frontend/src/lib/components/ExportButton/exportsLogic.test.ts b/frontend/src/lib/components/ExportButton/exportsLogic.test.ts
index bc3054673604..405f8510a89c 100644
--- a/frontend/src/lib/components/ExportButton/exportsLogic.test.ts
+++ b/frontend/src/lib/components/ExportButton/exportsLogic.test.ts
@@ -674,6 +674,28 @@ describe('exportsLogic', () => {
}
})
+ it('keeps polling a tracked export while its fetcher says it is still rendering', async () => {
+ // A retry records an exception on the generic row, so only the owner's fetcher knows it is not done.
+ jest.useFakeTimers()
+ try {
+ const pending = asset({ id: 32, export_format: ExporterFormat.JSON })
+ const retrying = asset({ id: 32, export_format: ExporterFormat.JSON, exception: 'Too busy' })
+ const fetchLatest = jest.fn().mockResolvedValue(pending)
+ jest.spyOn(api.exports, 'list').mockResolvedValue({ results: [retrying], count: 1 } as any)
+ const loadExportsSpy = jest.spyOn(logic.actions, 'loadExports')
+
+ logic.actions.trackExport(pending, fetchLatest)
+ await jest.advanceTimersByTimeAsync(30000)
+
+ // The first load comes from tracking the export; any later one is the poll.
+ expect(loadExportsSpy.mock.calls.length).toBeGreaterThan(1)
+ expect(logic.values.freshUndownloadedExports.map((a) => a.id)).toContain(32)
+ expect(lemonToast.error).not.toHaveBeenCalled()
+ } finally {
+ jest.useRealTimers()
+ }
+ })
+
it('replaces the failure toast with the upsell survey when the export limit is reached', async () => {
jest.spyOn(api.exports, 'create').mockRejectedValue({
data: { attr: 'export_limit_exceeded', detail: 'You hit the cap' },
diff --git a/frontend/src/lib/components/ExportButton/exportsLogic.ts b/frontend/src/lib/components/ExportButton/exportsLogic.ts
index 592e70206d40..19062cc403c1 100644
--- a/frontend/src/lib/components/ExportButton/exportsLogic.ts
+++ b/frontend/src/lib/components/ExportButton/exportsLogic.ts
@@ -342,9 +342,10 @@ export const exportsLogic = kea<exportsLogicType>([
: (listed ?? (await fetchExportOrNull(fresh.id)))
if (!latest || isRendering(latest)) {
// Still rendering, or a fetch miss. Release the claim so a later poll can
- // notify, and keep an out-of-list export polling.
+ // notify, and keep polling an export the list no longer shows as rendering, such as
+ // one whose owner retries after a failure the generic row still records.
cache.notifiedExportIds.delete(fresh.id)
- if (!listed) {
+ if (!listed || !isRendering(listed)) {
pending.push(latest ?? fresh)
}
continue
diff --git a/posthog/settings/web.py b/posthog/settings/web.py
index d520fc43bccb..cb1e5d58d590 100644
--- a/posthog/settings/web.py
+++ b/posthog/settings/web.py
@@ -743,6 +743,8 @@ SPECTACULAR_SETTINGS = {
#
# The choices come from a typing.Literal via get_args; there is no class.
"BlockedByEnum": ["x_frame_options", "frame_ancestors"],
+ # ai_observability's dataset and trace exports report the same states.
+ "ExportStatusEnum": "products.ai_observability.backend.facade.contracts.TRACE_EXPORT_STATUSES",
"FeatureFlagRequestTypeEnum": ["remote_evaluation", "local_evaluation"],
"PropertyFilterTypeEnum": [
"event",
diff --git a/products/ai_observability/backend/apps.py b/products/ai_observability/backend/apps.py
index 9830141f47ac..ef09a077d1e9 100644
--- a/products/ai_observability/backend/apps.py
+++ b/products/ai_observability/backend/apps.py
@@ -23,6 +23,22 @@ def _dataset_export_content_path(*, team_id: int, asset_id: int, export_context:
return dataset_export_content_path(team_id=team_id, asset_id=asset_id, export_context=export_context)
+def _export_trace_json(asset: "ExportedAsset") -> None:
+ from products.ai_observability.backend.tasks.trace_export import ( # noqa: PLC0415 -- keeps trace reads off the Django startup path
+ export_trace_json,
+ )
+
+ export_trace_json(asset)
+
+
+def _trace_export_content_path(*, team_id: int, asset_id: int, export_context: Mapping[str, object]) -> str | None:
+ from products.ai_observability.backend.presentation.trace_exports import ( # noqa: PLC0415 -- keeps the trace API off the Django startup path
+ trace_export_content_path,
+ )
+
+ return trace_export_content_path(team_id=team_id, asset_id=asset_id, export_context=export_context)
+
+
class AIObservabilityConfig(AppConfig):
default_auto_field = "django.db.models.BigAutoField"
name = "products.ai_observability.backend"
@@ -33,6 +49,10 @@ class AIObservabilityConfig(AppConfig):
# activity_logging module (not the evaluations viewset, which pulls scipy / google.genai /
# the ai_observability Temporal worker) so wiring it here stays off the django.setup() path.
from products.ai_observability.backend import activity_logging # noqa: F401, PLC0415
+ from products.ai_observability.backend.logic.traces.trace_export import ( # noqa: PLC0415 -- registration belongs at app population
+ TRACE_EXPORT_FORMAT,
+ TRACE_EXPORT_KIND,
+ )
from products.exports.backend.facade.exporters import ( # noqa: PLC0415 -- registration belongs at app population
DATASET_EXPORT_KIND,
register_export_format_handler,
@@ -44,3 +64,9 @@ class AIObservabilityConfig(AppConfig):
handler=_export_dataset_jsonl,
content_path=_dataset_export_content_path,
)
+ register_export_format_handler(
+ export_format=TRACE_EXPORT_FORMAT,
+ kind=TRACE_EXPORT_KIND,
+ handler=_export_trace_json,
+ content_path=_trace_export_content_path,
+ )
diff --git a/products/ai_observability/backend/facade/api.py b/products/ai_observability/backend/facade/api.py
index 0356bd70d663..9762c3db830e 100644
--- a/products/ai_observability/backend/facade/api.py
+++ b/products/ai_observability/backend/facade/api.py
@@ -1,14 +1,27 @@
-from collections.abc import Sequence
-from datetime import date, datetime
-from typing import TYPE_CHECKING
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime, timedelta
+from itertools import batched
+from typing import IO
+
+from django.utils.timezone import now
from posthog.schema import HogQLPropertyFilter
+from posthog.clickhouse.client.connection import Workload
from posthog.exceptions_capture import capture_exception
from posthog.models import Team, User
+from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
+from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.engineering_analytics.backend.facade import api as engineering_analytics_api
from products.engineering_analytics.backend.facade.contracts import BranchPRMatch, GitHubSourceNotConnectedError
+from products.exports.backend.facade.api import (
+ EXPORT_WORKFLOW_TIMEOUT,
+ ExportedAsset,
+ create_export_asset_async,
+ get_export_asset,
+ is_export_failure_final,
+)
from products.surveys.backend.facade.api import (
LinkedSurveyAnswer,
LinkedSurveyResponse,
@@ -37,6 +50,7 @@ from ..logic.traces.events_fallback import fallback_window
from ..logic.traces.feedback import FeedbackText, Score, TraceFeedback
from ..logic.traces.git import GitRef
from ..logic.traces.node import NodeEvent
+from ..logic.traces.node_contents_queries import load_trace_nodes
from ..logic.traces.summary import (
AIDataProcessingNotApprovedError as AIDataProcessingNotApprovedError,
FailedSummary,
@@ -52,7 +66,19 @@ from ..logic.traces.summary_store import fail_abandoned_summary, request_summary
from ..logic.traces.survey_feedback import THUMBS_UP, answer_kind, count_thumbs, survey_window
from ..logic.traces.timeline import TimelineRow
from ..logic.traces.trace import Trace
+from ..logic.traces.trace_export import (
+ MAX_TRACE_EXPORT_BYTES,
+ TRACE_EXPORT_FORMAT,
+ TRACE_EXPORT_KIND,
+ TRACE_EXPORT_NODE_BATCH_SIZE,
+ TRACE_EXPORT_TTL,
+ InvalidTraceExportRequestError,
+ TraceExportRequest,
+ TraceExportState,
+ TraceExportWriter,
+)
from ..logic.traces.trace_queries import (
+ TraceNodeRow,
load_trace,
load_trace_feedback_rows,
load_trace_git_rows,
@@ -66,9 +92,6 @@ from ..logic.traces.usage import Usage
from ..temporal.trace_summary_client import start_trace_summary
from . import contracts
-if TYPE_CHECKING:
- from products.access_control.backend.facade.user_access_control import UserAccessControl
-
class TraceNotFoundError(Exception):
pass
@@ -113,9 +136,7 @@ def get_trace_node(
root = load_trace_root(team, user, trace_id, timestamp_hint)
if not root.trace_found:
raise TraceNodeNotFoundError(node_id)
- if root.trace_event is None:
- return contracts.TraceNodeDetail(id=trace_id, kind="trace", error=None, metadata=_NO_METADATA, event=None)
- return _to_node_detail(trace_id, NodeEvent(row=root.trace_event))
+ return _to_root_detail(trace_id, root.trace_event)
row = load_trace_node(team, user, trace_id, node_id, timestamp_hint)
if row is None:
raise TraceNodeNotFoundError(node_id)
@@ -192,6 +213,12 @@ def _to_trace(trace: Trace) -> contracts.Trace:
)
+def _to_root_detail(trace_id: str, trace_event: TraceNodeRow | None) -> contracts.TraceNodeDetail:
+ if trace_event is None:
+ return contracts.TraceNodeDetail(id=trace_id, kind="trace", error=None, metadata=_NO_METADATA, event=None)
+ return _to_node_detail(trace_id, NodeEvent(row=trace_event))
+
+
def _to_git(ref: GitRef) -> contracts.TraceGit:
return contracts.TraceGit(branch=ref.branch, repo=ref.repo)
@@ -563,3 +590,114 @@ def _to_trace_summary(entry: SummaryEntry) -> contracts.TraceSummary:
case FailedSummary():
failure = contracts.TraceSummaryFailure(reason=entry.reason, message=entry.message)
return contracts.TraceSummary(status="failed", content=None, failure=failure)
+
+
+class TraceExportNotFoundError(Exception):
+ pass
+
+
+class TraceExportForbiddenError(Exception):
+ pass
+
+
+# Allows for the workflow's own timeout plus the time it takes to record a failure.
+_TRACE_EXPORT_STUCK_AFTER = EXPORT_WORKFLOW_TIMEOUT + timedelta(seconds=30)
+
+
+def create_trace_export(
+ team: Team, user: User, trace_id: str, timestamp_hint: datetime | None, *, was_impersonated: bool
+) -> contracts.TraceExport:
+ """Starts writing the trace and every node with its input and output to a JSON file the user downloads."""
+ request = TraceExportRequest(trace_id=trace_id, timestamp_hint=timestamp_hint)
+ asset = create_export_asset_async(
+ team=team,
+ created_by=user,
+ export_format=TRACE_EXPORT_FORMAT,
+ export_context=request.to_context(),
+ expires_after=now() + TRACE_EXPORT_TTL,
+ )
+ log_activity(
+ organization_id=team.organization_id,
+ team_id=team.id,
+ user=user,
+ was_impersonated=was_impersonated,
+ item_id=asset.id,
+ scope="ExportedAsset",
+ activity="exported",
+ detail=Detail(
+ name=asset.filename,
+ type=TRACE_EXPORT_KIND,
+ changes=[Change(type="ExportedAsset", action="exported", field="export_format", after=TRACE_EXPORT_FORMAT)],
+ ),
+ )
+ return _to_trace_export(asset)
+
+
+def get_trace_export(team: Team, user: User, trace_id: str, export_id: int) -> contracts.TraceExport:
+ """Raises `TraceExportNotFoundError` unless the user created this export of this trace."""
+ asset = get_export_asset(team_id=team.pk, asset_id=export_id)
+ if (
+ asset is None
+ or asset.created_by_id != user.id
+ or asset.export_format != TRACE_EXPORT_FORMAT
+ or exported_trace_id(asset.export_context or {}) != trace_id
+ ):
+ raise TraceExportNotFoundError(export_id)
+ return _to_trace_export(asset)
+
+
+def exported_trace_id(export_context: Mapping[str, object]) -> str | None:
+ try:
+ return TraceExportRequest.from_context(export_context).trace_id
+ except InvalidTraceExportRequestError:
+ return None
+
+
+def write_trace_export(team: Team, user: User, export_context: Mapping[str, object], stream: IO[bytes]) -> None:
+ """Writes `contracts.TraceExportFile` as JSON to the stream, reading as the user who requested the export.
+
+ Raises `TraceExportForbiddenError` or `TraceNotFoundError`, and the logic's `InvalidTraceExportRequestError` or
+ `TraceExportTooLargeError`.
+ """
+ request = TraceExportRequest.from_context(export_context)
+ # The export runs later without a request, so the view's permission check has to be repeated here.
+ access = UserAccessControl(user=user, team=team)
+ if not access.check_access_level_for_object(team, "member") or not access.check_access_level_for_resource(
+ "llm_analytics", "viewer"
+ ):
+ raise TraceExportForbiddenError(request.trace_id)
+ loaded = load_trace(team, user, request.trace_id, request.timestamp_hint, workload=Workload.OFFLINE)
+ if not loaded.rows:
+ raise TraceNotFoundError(request.trace_id)
+ trace = Trace(request.trace_id, loaded.rows, loaded.person)
+ writer = TraceExportWriter(
+ stream,
+ _to_trace(trace).model_dump_json(by_alias=True),
+ truncated=loaded.truncated,
+ max_bytes=MAX_TRACE_EXPORT_BYTES,
+ )
+ root = load_trace_root(team, user, trace.id, trace.created_at, workload=Workload.OFFLINE)
+ writer.add_node(_to_root_detail(trace.id, root.trace_event).model_dump_json(by_alias=True))
+ for node_ids in batched([row.event.id for row in trace.timeline.rows], TRACE_EXPORT_NODE_BATCH_SIZE, strict=False):
+ for row in load_trace_nodes(team, user, trace.id, node_ids, trace.created_at, workload=Workload.OFFLINE):
+ writer.add_node(_to_node_detail(row.uuid, NodeEvent(row=row)).model_dump_json(by_alias=True))
+ writer.close()
+
+
+def _to_trace_export(asset: ExportedAsset) -> contracts.TraceExport:
+ state = TraceExportState.of(
+ has_content=asset.has_content,
+ exception=asset.exception,
+ failure_is_final=is_export_failure_final(exception_type=asset.exception_type, failure_type=asset.failure_type),
+ created_at=asset.created_at,
+ now=now(),
+ stuck_after=_TRACE_EXPORT_STUCK_AFTER,
+ )
+ return contracts.TraceExport(
+ id=asset.id,
+ status=state.status,
+ filename=asset.filename,
+ created_at=asset.created_at,
+ expires_after=asset.expires_after,
+ exception=state.exception,
+ )
diff --git a/products/ai_observability/backend/facade/contracts.py b/products/ai_observability/backend/facade/contracts.py
index ade1f3510e3a..ab1919e0aeed 100644
--- a/products/ai_observability/backend/facade/contracts.py
+++ b/products/ai_observability/backend/facade/contracts.py
@@ -378,6 +378,31 @@ class TracePullRequestLookup(Contract):
)
+TraceExportStatus = Literal["pending", "complete", "failed"]
+TRACE_EXPORT_STATUSES: tuple[TraceExportStatus, ...] = get_args(TraceExportStatus)
+
+
+class TraceExport(Contract):
+ id: int = Field(description="The export id, used to read its status and download the file.")
+ status: TraceExportStatus = Field(description="Whether the file is still being written, ready, or failed.")
+ filename: str = Field(description="The name the downloaded JSON file gets.")
+ created_at: datetime = Field(description="When the export was requested.")
+ expires_after: datetime | None = Field(description="When the file is deleted.")
+ exception: str | None = Field(description="Why the export failed, null unless status is failed.")
+
+
+class TraceExportFile(Contract):
+ trace: Trace = Field(description="The trace as the trace endpoint returns it.")
+ truncated: bool = Field(
+ description="True when the trace has more events than an export reads. The file then holds the earliest "
+ "events only, and leaves out the later steps."
+ )
+ nodes: list[TraceNodeDetail] = Field(
+ description="Every node with its event properties as ingested, inputs and outputs included: the root first, "
+ "then the tree in pre-order."
+ )
+
+
AttentionReason = Literal["errored", "silent", "worse"]
BucketStatus = Literal["none", "dip", "normal"]
Interval = Literal["hour", "day"]
diff --git a/products/ai_observability/backend/logic/traces/node_contents_queries.py b/products/ai_observability/backend/logic/traces/node_contents_queries.py
index 23e8cebe2ebf..5e84241f9e2c 100644
--- a/products/ai_observability/backend/logic/traces/node_contents_queries.py
+++ b/products/ai_observability/backend/logic/traces/node_contents_queries.py
@@ -3,6 +3,7 @@ from datetime import datetime
from posthog.hogql import ast
+from posthog.clickhouse.client.connection import Workload
from posthog.models import Team, User
from .trace_queries import (
@@ -39,7 +40,13 @@ def _nodes_query(event_uuids: Sequence[str]) -> ast.SelectQuery:
def load_trace_nodes(
- team: Team, user: User | None, trace_id: str, node_ids: Sequence[str], timestamp_hint: datetime | None
+ team: Team,
+ user: User | None,
+ trace_id: str,
+ node_ids: Sequence[str],
+ timestamp_hint: datetime | None,
+ *,
+ workload: Workload = Workload.DEFAULT,
) -> list[TraceNodeRow]:
"""The content of each node of this trace in `node_ids`, in that order, skipping ids it does not hold.
@@ -57,6 +64,7 @@ def load_trace_nodes(
trace_id,
timestamp_hint,
widen_unhinted=False,
+ workload=workload,
)
rows = {row.uuid: row for row in map(_trace_node_row, results)}
return [rows[event_uuid] for event_uuid in event_uuids if event_uuid in rows]
diff --git a/products/ai_observability/backend/logic/traces/trace_export.py b/products/ai_observability/backend/logic/traces/trace_export.py
new file mode 100644
index 000000000000..1ad95241555a
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/trace_export.py
@@ -0,0 +1,107 @@
+from collections.abc import Mapping
+from datetime import datetime, timedelta
+from typing import IO, Self
+
+from posthog.dataclasses import frozen
+
+from ...facade.contracts import TraceExportStatus
+
+TRACE_EXPORT_KIND = "llm_trace"
+TRACE_EXPORT_FORMAT = "application/json"
+TRACE_EXPORT_TTL = timedelta(days=7)
+TRACE_EXPORT_NODE_BATCH_SIZE = 20
+MAX_TRACE_EXPORT_MEGABYTES = 250
+MAX_TRACE_EXPORT_BYTES = MAX_TRACE_EXPORT_MEGABYTES * 1_000_000
+# The largest file the export row may hold when object storage is off or fails.
+TRACE_EXPORT_DATABASE_FALLBACK_BYTES = 50_000_000
+TRACE_EXPORT_STUCK_MESSAGE = "This export took too long to finish. Try again."
+
+
+class InvalidTraceExportRequestError(ValueError):
+ pass
+
+
+class TraceExportTooLargeError(Exception):
+ pass
+
+
+@frozen
+class TraceExportRequest:
+ trace_id: str
+ timestamp_hint: datetime | None
+
+ @classmethod
+ def from_context(cls, context: Mapping[str, object]) -> Self:
+ trace_id = context.get("trace_id")
+ if context.get("kind") != TRACE_EXPORT_KIND or not isinstance(trace_id, str) or not trace_id:
+ raise InvalidTraceExportRequestError("The export context does not name a trace.")
+ hint = context.get("timestamp_hint")
+ if hint is None:
+ return cls(trace_id=trace_id, timestamp_hint=None)
+ if not isinstance(hint, str):
+ raise InvalidTraceExportRequestError("The export context has a malformed timestamp hint.")
+ try:
+ return cls(trace_id=trace_id, timestamp_hint=datetime.fromisoformat(hint))
+ except ValueError as error:
+ raise InvalidTraceExportRequestError("The export context has a malformed timestamp hint.") from error
+
+ def to_context(self) -> dict[str, object]:
+ return {
+ "kind": TRACE_EXPORT_KIND,
+ "trace_id": self.trace_id,
+ "timestamp_hint": self.timestamp_hint.isoformat() if self.timestamp_hint is not None else None,
+ "filename": f"trace-{self.trace_id[:64]}",
+ }
+
+
+@frozen
+class TraceExportState:
+ status: TraceExportStatus
+ exception: str | None
+
+ @classmethod
+ def of(
+ cls,
+ *,
+ has_content: bool,
+ exception: str | None,
+ failure_is_final: bool,
+ created_at: datetime,
+ now: datetime,
+ stuck_after: timedelta,
+ ) -> Self:
+ past_deadline = now > created_at + stuck_after
+ # The workflow retries a failure that is not final, and a later attempt clears the exception.
+ if exception and (failure_is_final or past_deadline):
+ return cls(status="failed", exception=exception)
+ if has_content:
+ return cls(status="complete", exception=None)
+ # Nothing records a failure when the workflow dies, so an export without content past its deadline has failed.
+ if past_deadline:
+ return cls(status="failed", exception=TRACE_EXPORT_STUCK_MESSAGE)
+ return cls(status="pending", exception=None)
+
+
+class TraceExportWriter:
+ """Writes `{"trace": ..., "nodes": [...]}` to a stream one node at a time, so the document never sits in memory."""
+
+ def __init__(self, stream: IO[bytes], trace_json: str, *, truncated: bool, max_bytes: int) -> None:
+ self._stream = stream
+ self._max_bytes = max_bytes
+ self._written = 0
+ self._has_nodes = False
+ self._write('{"trace":' + trace_json + ',"truncated":' + ("true" if truncated else "false") + ',"nodes":[')
+
+ def add_node(self, node_json: str) -> None:
+ self._write(("," if self._has_nodes else "") + node_json)
+ self._has_nodes = True
+
+ def close(self) -> None:
+ self._write("]}")
+
+ def _write(self, text: str) -> None:
+ chunk = text.encode()
+ if self._written + len(chunk) > self._max_bytes:
+ raise TraceExportTooLargeError(self._max_bytes)
+ self._stream.write(chunk)
+ self._written += len(chunk)
diff --git a/products/ai_observability/backend/logic/traces/trace_queries.py b/products/ai_observability/backend/logic/traces/trace_queries.py
index 4c6666ae71e9..594a7174a512 100644
--- a/products/ai_observability/backend/logic/traces/trace_queries.py
+++ b/products/ai_observability/backend/logic/traces/trace_queries.py
@@ -15,6 +15,7 @@ from posthog.hogql.context import HogQLContext
from posthog.hogql.database.database import Database
from posthog.hogql.query import execute_hogql_query
+from posthog.clickhouse.client.connection import Workload
from posthog.clickhouse.query_tagging import Product, tag_queries, tags_context
from posthog.dataclasses import frozen
from posthog.hogql_queries.ai.ai_table_resolver import query_ai_events
@@ -95,6 +96,10 @@ class LoadedTrace:
rows: tuple[TraceEventRow, ...]
person: PersonRow | None
+ @property
+ def truncated(self) -> bool:
+ return len(self.rows) >= MAX_TRACE_EVENTS
+
@frozen
class TraceRootLookup:
@@ -262,6 +267,7 @@ def _read(
*,
event_names: Sequence[str] = TRACE_EVENT_NAMES,
settings: HogQLGlobalSettings | None = None,
+ workload: Workload = Workload.DEFAULT,
) -> list[Sequence[Any]]:
tag_queries(name=name)
response = query_ai_events(
@@ -278,6 +284,7 @@ def _read(
},
posthog_tables_only=True,
settings=settings,
+ workload=workload,
)
return list(response.results or [])
@@ -359,7 +366,7 @@ def _trace_event_row(values: Sequence[Any]) -> TraceEventRow:
)
-def _read_person(team: Team, user: User | None, distinct_id: str) -> PersonRow:
+def _read_person(team: Team, user: User | None, distinct_id: str, workload: Workload) -> PersonRow:
name = "ai_trace_person"
with tags_context(product=Product.LLM_ANALYTICS):
tag_queries(name=name)
@@ -371,6 +378,7 @@ def _read_person(team: Team, user: User | None, distinct_id: str) -> PersonRow:
context=HogQLContext(
team_id=team.pk, team=team, user=user, database=Database.create_for_posthog_tables(team)
),
+ workload=workload,
)
email, person_name = response.results[0] if response.results else (None, None)
return PersonRow(distinct_id=distinct_id, email=read_text(email), name=read_text(person_name))
@@ -387,36 +395,53 @@ def _read_trace(
widen_unhinted: bool,
event_names: Sequence[str] = TRACE_EVENT_NAMES,
settings: HogQLGlobalSettings | None = None,
+ workload: Workload = Workload.DEFAULT,
) -> list[Sequence[Any]]:
- if timestamp_hint is not None:
+ def read(window: FallbackWindow | None) -> list[Sequence[Any]]:
return _read(
name,
build_query(),
team,
user,
trace_id,
- fallback_window(timestamp_hint),
+ window,
event_names=event_names,
settings=settings,
+ workload=workload,
)
- results = _read(name, build_query(), team, user, trace_id, None, event_names=event_names, settings=settings)
+
+ if timestamp_hint is not None:
+ return read(fallback_window(timestamp_hint))
+ results = read(None)
if results or not widen_unhinted:
return results
logger.warning("ai_trace_unhinted_events_fallback", team_id=team.pk, trace_id_length=len(trace_id), read=name)
- return _read(
- name, build_query(), team, user, trace_id, unhinted_window(), event_names=event_names, settings=settings
- )
+ return read(unhinted_window())
-def load_trace(team: Team, user: User | None, trace_id: str, timestamp_hint: datetime | None) -> LoadedTrace:
+def load_trace(
+ team: Team,
+ user: User | None,
+ trace_id: str,
+ timestamp_hint: datetime | None,
+ *,
+ workload: Workload = Workload.DEFAULT,
+) -> LoadedTrace:
rows = tuple(
_trace_event_row(values)
for values in _read_trace(
- "ai_trace_rows", _trace_rows_query, team, user, trace_id, timestamp_hint, widen_unhinted=True
+ "ai_trace_rows",
+ _trace_rows_query,
+ team,
+ user,
+ trace_id,
+ timestamp_hint,
+ widen_unhinted=True,
+ workload=workload,
)
)
distinct_id = trace_distinct_id(rows)
- person = _read_person(team, user, distinct_id) if distinct_id else None
+ person = _read_person(team, user, distinct_id, workload) if distinct_id else None
return LoadedTrace(rows=rows, person=person)
@@ -456,9 +481,18 @@ def load_trace_node(
return _trace_node_row(results[0]) if results else None
-def load_trace_root(team: Team, user: User | None, trace_id: str, timestamp_hint: datetime | None) -> TraceRootLookup:
+def load_trace_root(
+ team: Team,
+ user: User | None,
+ trace_id: str,
+ timestamp_hint: datetime | None,
+ *,
+ workload: Workload = Workload.DEFAULT,
+) -> TraceRootLookup:
def read(name: str, build_query: Callable[[], ast.SelectQuery]) -> list[Sequence[Any]]:
- return _read_trace(name, build_query, team, user, trace_id, timestamp_hint, widen_unhinted=False)
+ return _read_trace(
+ name, build_query, team, user, trace_id, timestamp_hint, widen_unhinted=False, workload=workload
+ )
results = read("ai_trace_root", lambda: _node_query(_equals("event", "$ai_trace")))
if results:
diff --git a/products/ai_observability/backend/presentation/trace_exports.py b/products/ai_observability/backend/presentation/trace_exports.py
new file mode 100644
index 000000000000..33142cd7c0e1
--- /dev/null
+++ b/products/ai_observability/backend/presentation/trace_exports.py
@@ -0,0 +1,23 @@
+from collections.abc import Mapping
+
+from django.urls import reverse
+
+from posthog.rate_limit import _UserBucketRateThrottle
+
+from ..facade import api
+from .trace_ids import encode_trace_id_segment
+
+
+class TraceExportRateThrottle(_UserBucketRateThrottle):
+ scope = "ai_trace_export"
+ rate = "20/hour"
+
+
+def trace_export_content_path(*, team_id: int, asset_id: int, export_context: Mapping[str, object]) -> str | None:
+ trace_id = api.exported_trace_id(export_context)
+ if trace_id is None:
+ return None
+ return reverse(
+ "project_ai_observability_traces-export-content",
+ kwargs={"parent_lookup_team_id": team_id, "pk": encode_trace_id_segment(trace_id), "export_id": asset_id},
+ )
diff --git a/products/ai_observability/backend/presentation/trace_ids.py b/products/ai_observability/backend/presentation/trace_ids.py
index 36023eb7b5d4..3511bbd07944 100644
--- a/products/ai_observability/backend/presentation/trace_ids.py
+++ b/products/ai_observability/backend/presentation/trace_ids.py
@@ -19,3 +19,7 @@ def decode_trace_id_segment(segment: str) -> str:
return base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4)).decode("utf-8")
except (binascii.Error, UnicodeDecodeError) as error:
raise MalformedTraceIdSegmentError(segment) from error
+
+
+def encode_trace_id_segment(trace_id: str) -> str:
+ return base64.urlsafe_b64encode(trace_id.encode("utf-8")).decode("ascii").rstrip("=")
diff --git a/products/ai_observability/backend/presentation/views.py b/products/ai_observability/backend/presentation/views.py
index 2271727a4473..030dfff39ed8 100644
--- a/products/ai_observability/backend/presentation/views.py
+++ b/products/ai_observability/backend/presentation/views.py
@@ -1,11 +1,17 @@
from collections.abc import Callable
from datetime import datetime
+from functools import partial
from typing import Any
+from django.db import transaction
+from django.http import HttpResponseBase
+
from drf_spectacular.types import OpenApiTypes
-from drf_spectacular.utils import OpenApiParameter, OpenApiResponse
+from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
from rest_framework import serializers, status, viewsets
from rest_framework.decorators import action
+from rest_framework.exceptions import NotAuthenticated
+from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.throttling import BaseThrottle
@@ -13,6 +19,8 @@ from posthog.api.documentation import _FallbackSerializer
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.clickhouse.query_tagging import Feature, tag_queries
+from posthog.event_usage import report_user_action
+from posthog.helpers.impersonation import is_impersonated
from posthog.models.user import User
from posthog.permissions import PostHogFeatureFlagPermission, get_authenticator_scopes
from posthog.rate_limit import (
@@ -23,9 +31,11 @@ from posthog.rate_limit import (
from posthog.scopes import scopes_not_covered
from products.engineering_analytics.backend.facade.contracts import ENGINEERING_ANALYTICS_FEATURE_FLAG
+from products.exports.backend.facade.api import get_export_asset, get_export_asset_content_response
from ..facade import api, contracts
from .query_concurrency import query_concurrency_slots
+from .trace_exports import TraceExportRateThrottle
from .trace_ids import MalformedTraceIdSegmentError, decode_trace_id_segment
@@ -88,9 +98,35 @@ class TraceSummaryRequestSerializer(serializers.Serializer):
)
+EXPORT_ID_PARAMETER = OpenApiParameter(
+ "export_id", OpenApiTypes.INT, OpenApiParameter.PATH, description="The export id the create call returned."
+)
+EXPORT_NOT_FOUND_RESPONSE = OpenApiResponse(description="You have no export with this id for this trace.")
+
+
+# Gives the export request body its own schema, apart from the trace read's query parameters.
+class TraceExportCreateSerializer(TraceQuerySerializer):
+ pass
+
+
+class TraceExportErrorSerializer(serializers.Serializer):
+ detail = serializers.CharField(help_text="Why the file cannot be downloaded yet.")
+
+
class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
scope_object = "llm_analytics"
- scope_object_read_actions = ["retrieve", "node", "evaluations", "clusters", "feedback", "search", "summary"]
+ scope_object_read_actions = [
+ "retrieve",
+ "node",
+ "evaluations",
+ "clusters",
+ "feedback",
+ "search",
+ "summary",
+ "exports",
+ "export_status",
+ "export_content",
+ ]
scope_object_write_actions = ["request_summary"]
# Traces are project-wide data, so a grant on a single llm_analytics object must not open them.
requires_resource_level_access = True
@@ -367,3 +403,98 @@ class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
lambda user, hint: api.get_trace_pull_request(self.team, user, self.user_access_control, trace_id, hint),
)
return Response(lookup.model_dump(mode="json", by_alias=True))
+
+ @validated_request(
+ request_serializer=TraceExportCreateSerializer,
+ parameters=[TRACE_ID_PARAMETER],
+ responses={
+ 201: OpenApiResponse(response=contracts.TraceExport),
+ 400: OpenApiResponse(description="The timestamp hint or the encoded trace id is malformed."),
+ 429: OpenApiResponse(description="Too many exports were requested."),
+ },
+ operation_id="ai_observability_traces_exports_create",
+ )
+ @action(detail=True, methods=["POST"], url_path="exports", throttle_classes=[TraceExportRateThrottle])
+ def exports(self, request: ValidatedRequest, pk: str, **kwargs: Any) -> Response:
+ """Starts writing the trace and every node, inputs and outputs included, to a JSON file. Poll the export until it completes, then download it."""
+ try:
+ trace_id = decode_trace_id_segment(pk)
+ except MalformedTraceIdSegmentError:
+ return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)
+ export = api.create_trace_export(
+ self.team,
+ _user(request),
+ trace_id,
+ request.validated_data.get("timestamp_hint"),
+ was_impersonated=is_impersonated(request),
+ )
+ return Response(export.model_dump(mode="json", by_alias=True), status=status.HTTP_201_CREATED)
+
+ @validated_request(
+ parameters=[TRACE_ID_PARAMETER, EXPORT_ID_PARAMETER],
+ responses={
+ 200: OpenApiResponse(response=contracts.TraceExport),
+ 400: OpenApiResponse(description="The encoded trace id is malformed."),
+ 404: EXPORT_NOT_FOUND_RESPONSE,
+ },
+ operation_id="ai_observability_traces_exports_retrieve",
+ )
+ @action(detail=True, methods=["GET"], url_path=r"exports/(?P<export_id>\d+)")
+ def export_status(self, request: ValidatedRequest, pk: str, export_id: str, **kwargs: Any) -> Response:
+ """The state of one of your exports of this trace."""
+ try:
+ export = self._trace_export(request, pk, export_id)
+ except MalformedTraceIdSegmentError:
+ return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)
+ except api.TraceExportNotFoundError:
+ return Response({"detail": "Export not found."}, status=status.HTTP_404_NOT_FOUND)
+ return Response(export.model_dump(mode="json", by_alias=True))
+
+ @extend_schema(
+ parameters=[TRACE_ID_PARAMETER, EXPORT_ID_PARAMETER],
+ responses={
+ (200, "application/json"): OpenApiResponse(response=contracts.TraceExportFile),
+ 400: OpenApiResponse(description="The encoded trace id is malformed."),
+ 404: EXPORT_NOT_FOUND_RESPONSE,
+ 409: OpenApiResponse(
+ response=TraceExportErrorSerializer, description="The export is still being written, or failed."
+ ),
+ },
+ operation_id="ai_observability_traces_exports_content_retrieve",
+ )
+ @action(detail=True, methods=["GET"], url_path=r"exports/(?P<export_id>\d+)/content")
+ def export_content(self, request: Request, pk: str, export_id: str, **kwargs: Any) -> HttpResponseBase:
+ """Downloads a completed export as a JSON file."""
+ try:
+ export = self._trace_export(request, pk, export_id)
+ except MalformedTraceIdSegmentError:
+ return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)
+ except api.TraceExportNotFoundError:
+ return Response({"detail": "Export not found."}, status=status.HTTP_404_NOT_FOUND)
+ asset = get_export_asset(team_id=self.team.pk, asset_id=export.id)
+ if export.status != "complete" or asset is None:
+ detail = export.exception or "The export is still being prepared."
+ return Response({"detail": detail}, status=status.HTTP_409_CONFLICT)
+ response = get_export_asset_content_response(asset=asset, download=True)
+ transaction.on_commit(
+ partial(
+ report_user_action,
+ request.user,
+ "llma trace export downloaded",
+ {"export_id": export.id},
+ team=self.team,
+ request=request,
+ ),
+ robust=True,
+ )
+ return response
+
+ def _trace_export(self, request: Request, pk: str, export_id: str) -> contracts.TraceExport:
+ return api.get_trace_export(self.team, _user(request), decode_trace_id_segment(pk), int(export_id))
+
+
+def _user(request: Request) -> User:
+ # An export runs later as the user who asked for it, so unlike a trace read it cannot go without one.
+ if not isinstance(request.user, User):
+ raise NotAuthenticated()
+ return request.user
diff --git a/products/ai_observability/backend/tasks/__init__.py b/products/ai_observability/backend/tasks/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/ai_observability/backend/tasks/trace_export.py b/products/ai_observability/backend/tasks/trace_export.py
new file mode 100644
index 000000000000..699e234604db
--- /dev/null
+++ b/products/ai_observability/backend/tasks/trace_export.py
@@ -0,0 +1,43 @@
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from products.exports.backend.facade.api import InvalidExportContext, save_export_asset_content_from_file
+
+from ..facade import api
+from ..logic.traces.trace_export import (
+ MAX_TRACE_EXPORT_MEGABYTES,
+ TRACE_EXPORT_DATABASE_FALLBACK_BYTES,
+ InvalidTraceExportRequestError,
+ TraceExportTooLargeError,
+)
+
+if TYPE_CHECKING:
+ from products.exports.backend.facade.api import ExportedAsset
+
+
+def export_trace_json(asset: "ExportedAsset") -> None:
+ """Writes the trace export file. Failures the user can act on raise `InvalidExportContext`, which is not retried."""
+ if asset.created_by is None:
+ raise InvalidExportContext("The trace export configuration is invalid.", reportable=True)
+ file_path: str | None = None
+ try:
+ with tempfile.NamedTemporaryFile(mode="wb", suffix=".json", delete=False) as export_file:
+ file_path = export_file.name
+ api.write_trace_export(asset.team, asset.created_by, asset.export_context or {}, export_file)
+ save_export_asset_content_from_file(
+ asset=asset, file_path=file_path, max_database_bytes=TRACE_EXPORT_DATABASE_FALLBACK_BYTES
+ )
+ except InvalidTraceExportRequestError as error:
+ raise InvalidExportContext("The trace export configuration is invalid.", reportable=True) from error
+ except api.TraceNotFoundError as error:
+ raise InvalidExportContext("This trace is no longer available.") from error
+ except api.TraceExportForbiddenError as error:
+ raise InvalidExportContext("You no longer have access to this trace.") from error
+ except TraceExportTooLargeError as error:
+ raise InvalidExportContext(
+ f"This trace is larger than {MAX_TRACE_EXPORT_MEGABYTES} MB, so it can't be exported."
+ ) from error
+ finally:
+ if file_path is not None:
+ Path(file_path).unlink(missing_ok=True)
diff --git a/products/ai_observability/backend/tests/logic/traces/test_trace_export.py b/products/ai_observability/backend/tests/logic/traces/test_trace_export.py
new file mode 100644
index 000000000000..03cfd06f2bee
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_trace_export.py
@@ -0,0 +1,94 @@
+import io
+import json
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from parameterized import parameterized
+
+from products.ai_observability.backend.logic.traces.trace_export import (
+ TRACE_EXPORT_STUCK_MESSAGE,
+ InvalidTraceExportRequestError,
+ TraceExportRequest,
+ TraceExportState,
+ TraceExportTooLargeError,
+ TraceExportWriter,
+)
+
+T0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)
+
+
[email protected]([("with a hint", T0), ("without a hint", None)])
+def test_the_request_round_trips_through_the_export_context(_name: str, timestamp_hint: datetime | None) -> None:
+ request = TraceExportRequest(trace_id="a/b c", timestamp_hint=timestamp_hint)
+
+ assert TraceExportRequest.from_context(json.loads(json.dumps(request.to_context()))) == request
+ assert request.to_context()["filename"] == "trace-a/b c"
+
+
+ [
+ ("another kind", {"kind": "dataset", "trace_id": "trace-1"}),
+ ("no trace id", {"kind": "llm_trace"}),
+ ("an empty trace id", {"kind": "llm_trace", "trace_id": ""}),
+ ("a malformed hint", {"kind": "llm_trace", "trace_id": "trace-1", "timestamp_hint": "yesterday"}),
+ ]
+)
+def test_a_context_that_is_not_a_trace_export_is_refused(_name: str, context: dict[str, object]) -> None:
+ with pytest.raises(InvalidTraceExportRequestError):
+ TraceExportRequest.from_context(context)
+
+
+ [
+ ("content", True, None, True, 1, ("complete", None)),
+ ("a final failure", False, "Boom", True, 1, ("failed", "Boom")),
+ ("a final failure with content", True, "Boom", True, 1, ("failed", "Boom")),
+ ("a failure the workflow retries", False, "Boom", False, 1, ("pending", None)),
+ ("a retried failure past the deadline", False, "Boom", False, 61, ("failed", "Boom")),
+ ("no content yet", False, None, True, 1, ("pending", None)),
+ ("no content past the deadline", False, None, True, 61, ("failed", TRACE_EXPORT_STUCK_MESSAGE)),
+ ]
+)
+def test_export_state(
+ _name: str,
+ has_content: bool,
+ exception: str | None,
+ failure_is_final: bool,
+ minutes_old: int,
+ expected: tuple[str, str | None],
+) -> None:
+ state = TraceExportState.of(
+ has_content=has_content,
+ exception=exception,
+ failure_is_final=failure_is_final,
+ created_at=T0,
+ now=T0 + timedelta(minutes=minutes_old),
+ stuck_after=timedelta(minutes=60),
+ )
+
+ assert (state.status, state.exception) == expected
+
+
+ [("nodes", ['{"id":"a"}', '{"id":"b"}'], False), ("no nodes", [], False), ("a truncated trace", [], True)]
+)
+def test_the_writer_streams_one_json_document(_name: str, nodes: list[str], truncated: bool) -> None:
+ stream = io.BytesIO()
+ writer = TraceExportWriter(stream, '{"id":"trace-1"}', truncated=truncated, max_bytes=1_000)
+ for node in nodes:
+ writer.add_node(node)
+ writer.close()
+
+ assert json.loads(stream.getvalue()) == {
+ "trace": {"id": "trace-1"},
+ "truncated": truncated,
+ "nodes": [json.loads(node) for node in nodes],
+ }
+
+
+def test_the_writer_stops_at_the_byte_cap() -> None:
+ writer = TraceExportWriter(io.BytesIO(), '{"id":"trace-1"}', truncated=False, max_bytes=60)
+
+ with pytest.raises(TraceExportTooLargeError):
+ writer.add_node(json.dumps({"content": "x" * 100}))
diff --git a/products/ai_observability/backend/tests/test_facade_api.py b/products/ai_observability/backend/tests/test_facade_api.py
index 98c2f0562813..5315ab622b28 100644
--- a/products/ai_observability/backend/tests/test_facade_api.py
+++ b/products/ai_observability/backend/tests/test_facade_api.py
@@ -1,18 +1,27 @@
+import tempfile
from collections.abc import Callable
+from contextlib import suppress
from datetime import UTC, datetime, timedelta
+from pathlib import Path
import pytest
-from posthog.test.base import BaseTest, ClickhouseTestMixin
+from posthog.test.base import APIBaseTest, BaseTest, ClickhouseTestMixin
from unittest.mock import MagicMock, call, patch
from parameterized import parameterized
+from posthog.clickhouse.client.connection import Workload
from posthog.constants import AvailableFeature
-from posthog.models import Team, User
+from posthog.models import Team
+from posthog.models.ai_events.test_util import bulk_create_ai_events
from posthog.models.event.util import bulk_create_events
+from posthog.models.organization import OrganizationMembership
+from posthog.models.user import User
+from posthog.tasks import exporter
from products.access_control.backend.models.access_control import AccessControl
from products.ai_observability.backend.facade import api, contracts
+from products.ai_observability.backend.logic.traces import trace_queries
from products.ai_observability.backend.logic.traces.summary import (
FailedSummary,
PendingSummary,
@@ -28,11 +37,13 @@ from products.ai_observability.backend.logic.traces.summary_store import (
summary_key,
write_summary,
)
+from products.ai_observability.backend.logic.traces.trace_export import TraceExportRequest
from products.ai_observability.backend.logic.traces.trace_queries import FeedbackEventRow, LoadedTrace, TraceEventRow
from products.ai_observability.backend.models.evaluations import Evaluation
from products.engineering_analytics.backend.facade import api as engineering_analytics_api
from products.engineering_analytics.backend.facade.contracts import BranchPRMatch, GitHubSourceNotConnectedError
from products.event_definitions.backend.models.property_definition import PropertyDefinition
+from products.exports.backend.facade.api import ExportedAsset, InvalidExportContext, read_export_asset_content
from products.surveys.backend.facade.api import (
LinkedSurveyAnswer,
LinkedSurveyResponse,
@@ -50,6 +61,7 @@ from .logic.traces.rows import (
make_feedback_row,
make_row,
)
+from .logic.traces.test_trace_queries import TraceEventsMixin
from .property_access import hide_event_property
T0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)
@@ -575,3 +587,162 @@ class TestGetTracePullRequest:
lookup, resolve_branch = self._lookup(rows, **resolve)
assert (lookup.pull_request, resolve_branch.called) == (None, resolves)
+
+
+SPAN = "00000000-0000-0000-0000-000000000011"
+GENERATION = "00000000-0000-0000-0000-000000000012"
+LATER = "00000000-0000-0000-0000-000000000013"
+ROOT_EVENT = "00000000-0000-0000-0000-000000000014"
+QUESTION = [{"role": "user", "content": "Which plan fits a team of five?"}]
+ANSWER = [{"role": "assistant", "content": "The team plan."}]
+
+
+class TestTraceExportFile(TraceEventsMixin, ClickhouseTestMixin, APIBaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ bulk_create_ai_events(
+ [
+ self._event(ROOT_EVENT, event="$ai_trace", properties={"$ai_input_state": {"question": "Why?"}}),
+ self._event(
+ SPAN,
+ timestamp=T0 + timedelta(seconds=1),
+ properties={"$ai_parent_id": "trace-1", "$ai_span_id": "span-1"},
+ ),
+ self._event(
+ GENERATION,
+ event="$ai_generation",
+ timestamp=T0 + timedelta(seconds=2),
+ properties={
+ "$ai_parent_id": "span-1",
+ "$ai_input": QUESTION,
+ "$ai_output_choices": ANSWER,
+ "$ai_provider": "openai",
+ },
+ ),
+ self._event(
+ LATER, timestamp=T0 + timedelta(milliseconds=1500), properties={"$ai_parent_id": "trace-1"}
+ ),
+ ]
+ )
+
+ def _export(self, trace_id: str = "trace-1", created_by: User | None = None) -> ExportedAsset:
+ asset = ExportedAsset.objects.create(
+ team=self.team,
+ export_format="application/json",
+ export_context=TraceExportRequest(trace_id=trace_id, timestamp_hint=T0).to_context(),
+ created_by=created_by or self.user,
+ )
+ with suppress(InvalidExportContext):
+ exporter.export_asset_direct(asset)
+ asset.refresh_from_db()
+ return asset
+
+ def _file(self, asset: ExportedAsset) -> contracts.TraceExportFile:
+ content = read_export_asset_content(team_id=self.team.pk, asset_id=asset.id)
+ assert content is not None, asset.exception
+ return contracts.TraceExportFile.model_validate_json(content)
+
+ @parameterized.expand([("one batch", 20), ("a batch per node", 1)])
+ def test_writes_the_trace_and_every_node_with_its_io(self, _name: str, batch_size: int) -> None:
+ with (
+ patch.object(api, "TRACE_EXPORT_NODE_BATCH_SIZE", batch_size),
+ patch.object(trace_queries, "query_ai_events", wraps=trace_queries.query_ai_events) as reads,
+ patch.object(trace_queries, "execute_hogql_query", wraps=trace_queries.execute_hogql_query) as person_reads,
+ ):
+ asset = self._export()
+
+ file = self._file(asset)
+ assert asset.exception is None
+ assert person_reads.call_count == 1
+ assert {call.kwargs["workload"] for call in [*reads.call_args_list, *person_reads.call_args_list]} == {
+ Workload.OFFLINE
+ }
+ assert file.trace.id == "trace-1"
+ assert file.truncated is False
+ assert [node.id for node in file.nodes] == ["trace-1", SPAN, GENERATION, LATER]
+ root, generation = file.nodes[0].event, file.nodes[2].event
+ assert root is not None and root.properties["$ai_input_state"] == {"question": "Why?"}
+ assert generation is not None and generation.properties["$ai_input"] == QUESTION
+
+ def test_a_trace_over_the_event_limit_exports_what_was_read_and_says_so(self) -> None:
+ with patch.object(trace_queries, "MAX_TRACE_EVENTS", 2):
+ asset = self._export()
+
+ file = self._file(asset)
+ assert asset.exception is None
+ assert file.truncated is True
+ assert [node.id for node in file.nodes] == ["trace-1", SPAN]
+
+ def test_leaves_out_properties_the_creator_may_not_read(self) -> None:
+ hide_event_property(self.team, self.user, "$ai_input")
+
+ generation = self._file(self._export()).nodes[2].event
+
+ assert generation is not None
+ assert "$ai_input" not in generation.properties
+ assert generation.properties["$ai_provider"] == "openai"
+
+ def test_fails_when_the_creator_lost_access(self) -> None:
+ self.organization.available_product_features = [
+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},
+ {"key": AvailableFeature.ROLE_BASED_ACCESS, "name": AvailableFeature.ROLE_BASED_ACCESS},
+ ]
+ self.organization.save()
+ member = User.objects.create_and_join(self.organization, "[email protected]", "testtest")
+ AccessControl.objects.create(
+ team=self.team,
+ resource="llm_analytics",
+ access_level="none",
+ organization_member=OrganizationMembership.objects.get(user=member, organization=self.organization),
+ )
+
+ asset = self._export(created_by=member)
+
+ assert (asset.exception, asset.has_content) == ("You no longer have access to this trace.", False)
+
+ @parameterized.expand(
+ [
+ ("a missing trace", "trace-2", None, "This trace is no longer available."),
+ ("a file over the cap", "trace-1", 10, "This trace is larger than 250 MB, so it can't be exported."),
+ ]
+ )
+ def test_fails_as_a_user_error_and_leaves_no_file(
+ self, _name: str, trace_id: str, max_bytes: int | None, message: str
+ ) -> None:
+ with (
+ tempfile.TemporaryDirectory() as temporary_directory,
+ patch.object(api, "MAX_TRACE_EXPORT_BYTES", max_bytes or api.MAX_TRACE_EXPORT_BYTES),
+ patch.object(tempfile, "tempdir", temporary_directory),
+ ):
+ asset = self._export(trace_id)
+ leftover_files = list(Path(temporary_directory).iterdir())
+
+ assert (asset.exception, asset.failure_type) == (message, "user")
+ assert leftover_files == []
+
+
+class TestGetTraceExport(BaseTest):
+ def _asset(self, *, trace_id: str = "trace-1", created_by: User | None = None, kind: str = "llm_trace") -> int:
+ context = {**TraceExportRequest(trace_id=trace_id, timestamp_hint=None).to_context(), "kind": kind}
+ return ExportedAsset.objects.create(
+ team=self.team, export_format="application/json", export_context=context, created_by=created_by or self.user
+ ).id
+
+ def test_reads_my_export_of_this_trace(self) -> None:
+ export = api.get_trace_export(self.team, self.user, "trace-1", self._asset())
+
+ assert (export.status, export.exception) == ("pending", None)
+
+ @parameterized.expand(
+ [
+ ("another user's export", lambda test: test._asset(created_by=test._teammate()), "trace-1"),
+ ("an export of another trace", lambda test: test._asset(), "trace-2"),
+ ("an export of another kind", lambda test: test._asset(kind="dataset"), "trace-1"),
+ ]
+ )
+ def test_hides(self, _name: str, asset_for: Callable[["TestGetTraceExport"], int], trace_id: str) -> None:
+ with pytest.raises(api.TraceExportNotFoundError):
+ api.get_trace_export(self.team, self.user, trace_id, asset_for(self))
+
+ def _teammate(self) -> User:
+ return User.objects.create_and_join(self.organization, "[email protected]", "testtest")
diff --git a/products/ai_observability/backend/tests/test_trace_ids.py b/products/ai_observability/backend/tests/test_trace_ids.py
index dba3d401de69..227fa572c704 100644
--- a/products/ai_observability/backend/tests/test_trace_ids.py
+++ b/products/ai_observability/backend/tests/test_trace_ids.py
@@ -5,6 +5,7 @@ from parameterized import parameterized
from products.ai_observability.backend.presentation.trace_ids import (
MalformedTraceIdSegmentError,
decode_trace_id_segment,
+ encode_trace_id_segment,
)
@@ -19,8 +20,9 @@ class TestDecodeTraceIdSegment(SimpleTestCase):
("é/ü", "w6kvw7w"),
]
)
- def test_decodes_the_shared_vectors(self, trace_id: str, segment: str) -> None:
+ def test_encodes_and_decodes_the_shared_vectors(self, trace_id: str, segment: str) -> None:
assert decode_trace_id_segment(segment) == trace_id
+ assert encode_trace_id_segment(trace_id) == segment
@parameterized.expand(
[
diff --git a/products/ai_observability/backend/tests/test_trace_views.py b/products/ai_observability/backend/tests/test_trace_views.py
index ad4506ec89ae..68d6df2afda0 100644
--- a/products/ai_observability/backend/tests/test_trace_views.py
+++ b/products/ai_observability/backend/tests/test_trace_views.py
@@ -1,10 +1,10 @@
import base64
from datetime import UTC, datetime, timedelta
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from urllib.parse import urlencode
from posthog.test.base import APIBaseTest, ClickhouseTestMixin
-from unittest.mock import MagicMock, patch
+from unittest.mock import ANY, AsyncMock, MagicMock, patch
from parameterized import parameterized
@@ -28,6 +28,7 @@ from products.ai_observability.backend.models.review_queues import ReviewQueue
from products.engineering_analytics.backend.facade import api as engineering_analytics_api
from products.engineering_analytics.backend.facade.contracts import ENGINEERING_ANALYTICS_FEATURE_FLAG, BranchPRMatch
from products.event_definitions.backend.models.property_definition import PropertyDefinition
+from products.exports.backend.facade.api import ExportedAsset
from .logic.traces.rows import make_cluster, make_cluster_run_event, make_evaluation_result_event
@@ -572,7 +573,8 @@ class TestTraceSearchView(ClickhouseTestMixin, APIBaseTest):
class TestTraceViewSetResourceLevelAccess(ClickhouseTestMixin, APIBaseTest):
- def test_a_grant_on_one_object_does_not_open_traces(self) -> None:
+ @parameterized.expand([("the trace", "get", ""), ("an export", "post", "exports/")])
+ def test_a_grant_on_one_object_does_not_open_traces(self, _name: str, method: str, path: str) -> None:
self.organization.available_product_features = [
{"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},
{"key": AvailableFeature.ROLE_BASED_ACCESS, "name": AvailableFeature.ROLE_BASED_ACCESS},
@@ -594,7 +596,8 @@ class TestTraceViewSetResourceLevelAccess(ClickhouseTestMixin, APIBaseTest):
_create_trace(self.team)
self.client.force_login(member)
- response = self.client.get(f"/api/projects/{self.team.id}/ai_observability/traces/{_encode('trace-1')}/")
+ url = f"/api/projects/{self.team.id}/ai_observability/traces/{_encode('trace-1')}/{path}"
+ response = getattr(self.client, method)(url)
assert response.status_code == 403, response.content
@@ -742,3 +745,101 @@ class TestTracePullRequestView(ClickhouseTestMixin, APIBaseTest):
response, resolve = self._get("trace-1")
assert (response.status_code, resolve.called) == (400, False)
+
+
+class TestTraceExportViews(APIBaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ async_connect = patch("products.exports.backend.facade.api.async_connect", new_callable=AsyncMock)
+ self.start_workflow = async_connect.start().return_value.start_workflow
+ self.addCleanup(async_connect.stop)
+
+ def _url(self, segment: str, export_id: int | None = None, suffix: str = "") -> str:
+ url = f"/api/projects/{self.team.id}/ai_observability/traces/{segment}/exports/"
+ return url if export_id is None else f"{url}{export_id}/{suffix}"
+
+ def _create(self, trace_id: str = "a/b") -> dict[str, Any]:
+ response = self.client.post(self._url(_encode(trace_id)), {"timestamp_hint": T0.isoformat()}, format="json")
+ assert response.status_code == 201, response.content
+ return response.json()
+
+ def test_creates_reports_and_serves_the_export_to_its_creator(self) -> None:
+ export = self._create()
+ export_id = export["id"]
+
+ assert set(export) == {"id", "status", "filename", "createdAt", "expiresAfter", "exception"}
+ assert (export["status"], export["exception"]) == ("pending", None)
+ self.start_workflow.assert_awaited_once()
+ assert self.client.get(self._url(_encode("a/b"), export_id)).json()["status"] == "pending"
+ assert self.client.get(self._url(_encode("a/b"), export_id, "content/")).status_code == 409
+
+ ExportedAsset.objects.filter(id=export_id).update(content=b'{"trace":{},"nodes":[]}')
+ content = self.client.get(self._url(_encode("a/b"), export_id, "content/"))
+
+ assert content.status_code == 200
+ assert content["Content-Disposition"].startswith("attachment")
+ assert self.client.get(f"/api/projects/{self.team.id}/exports/{export_id}/").status_code == 404
+ self.assertRedirects(
+ self.client.get(f"/api/projects/{self.team.id}/exports/{export_id}/content"),
+ self._url(_encode("a/b"), export_id, "content"),
+ fetch_redirect_response=False,
+ )
+
+ @parameterized.expand([("another user", True, "a/b"), ("another trace", False, "c")])
+ def test_status_and_content_are_404_for(self, _name: str, as_teammate: bool, url_trace_id: str) -> None:
+ export_id = self._create()["id"]
+ if as_teammate:
+ self.client.force_login(User.objects.create_and_join(self.organization, "[email protected]", "testtest"))
+
+ for suffix in ("", "content/"):
+ assert self.client.get(self._url(_encode(url_trace_id), export_id, suffix)).status_code == 404
+
+ def test_an_export_whose_workflow_never_started_fails_at_once(self) -> None:
+ self.start_workflow.side_effect = RuntimeError("Temporal is unreachable")
+
+ export = self._create()
+ status = self.client.get(self._url(_encode("a/b"), export["id"])).json()
+
+ expected = ("failed", "The export could not be started. Try again.")
+ assert (export["status"], export["exception"]) == expected
+ assert (status["status"], status["exception"]) == expected
+
+ @patch("products.ai_observability.backend.presentation.views.report_user_action")
+ def test_tracks_a_download(self, report_user_action: MagicMock) -> None:
+ export_id = self._create()["id"]
+ ExportedAsset.objects.filter(id=export_id).update(content=b'{"trace":{},"nodes":[]}')
+
+ with self.captureOnCommitCallbacks(execute=True):
+ self.client.get(self._url(_encode("a/b"), export_id, "content/"))
+
+ report_user_action.assert_called_once_with(
+ self.user, "llma trace export downloaded", {"export_id": export_id}, team=self.team, request=ANY
+ )
+
+ def test_a_failed_export_reports_its_reason(self) -> None:
+ export_id = self._create()["id"]
+ ExportedAsset.objects.filter(id=export_id).update(
+ exception="This trace is no longer available.", exception_type="InvalidExportContext"
+ )
+
+ status = self.client.get(self._url(_encode("a/b"), export_id)).json()
+ content = self.client.get(self._url(_encode("a/b"), export_id, "content/"))
+
+ assert (status["status"], status["exception"]) == ("failed", "This trace is no longer available.")
+ assert (content.status_code, content.json()["detail"]) == (409, "This trace is no longer available.")
+
+ @parameterized.expand([("a malformed hint", _encode("a/b"), "yesterday"), ("an unencoded trace id", "a+b", None)])
+ def test_rejects(self, _name: str, segment: str, hint: str | None) -> None:
+ response = self.client.post(self._url(segment), {"timestamp_hint": hint} if hint else {}, format="json")
+
+ assert response.status_code == 400
+ self.start_workflow.assert_not_awaited()
+
+ @patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True)
+ @patch("products.ai_observability.backend.presentation.trace_exports.TraceExportRateThrottle.rate", new="1/day")
+ def test_throttles_exports_per_user(self, _rate_limit: MagicMock) -> None:
+ self._create()
+
+ assert self.client.post(self._url(_encode("a/b")), {}, format="json").status_code == 429
+ self.client.force_login(User.objects.create_and_join(self.organization, "[email protected]", "testtest"))
+ self._create()
diff --git a/products/ai_observability/frontend/datasets/aiObservabilityDatasetLogic.ts b/products/ai_observability/frontend/datasets/aiObservabilityDatasetLogic.ts
index 40df3b272edd..bfa8c68116ed 100644
--- a/products/ai_observability/frontend/datasets/aiObservabilityDatasetLogic.ts
+++ b/products/ai_observability/frontend/datasets/aiObservabilityDatasetLogic.ts
@@ -32,7 +32,7 @@ import { urls } from '~/scenes/urls'
import { AccessControlLevel, AccessControlResourceType, Breadcrumb, ExportedAssetType, ExporterFormat } from '~/types'
import type { ProductIntentProperties } from '../../../../frontend/src/lib/utils/product-intents'
-import { CodeEnumApi, DatasetExportReadStatusEnumApi } from '../generated/api.schemas'
+import { CodeEnumApi, ExportStatusEnumApi } from '../generated/api.schemas'
import type {
DatasetExportReadApi,
DatasetItemReadApi,
@@ -114,7 +114,7 @@ function datasetExportToExportedAsset(datasetExport: DatasetExportReadApi): Expo
return {
id: datasetExport.id,
export_format: ExporterFormat.JSONL,
- has_content: datasetExport.status === DatasetExportReadStatusEnumApi.Complete,
+ has_content: datasetExport.status === ExportStatusEnumApi.Complete,
filename: datasetExport.filename,
created_at: datasetExport.created_at,
expires_after: datasetExport.expires_after,
@@ -1181,7 +1181,7 @@ export const aiObservabilityDatasetLogic = kea<aiObservabilityDatasetLogicType>(
},
exportDatasetSuccess: ({ datasetExport }) => {
- if (datasetExport.status === DatasetExportReadStatusEnumApi.Failed) {
+ if (datasetExport.status === ExportStatusEnumApi.Failed) {
lemonToast.error(datasetExport.exception || "Couldn't start dataset export. Try again.")
return
}
diff --git a/products/ai_observability/frontend/generated/api.schemas.ts b/products/ai_observability/frontend/generated/api.schemas.ts
index 22e5876ab9f2..80fe61661fc4 100644
--- a/products/ai_observability/frontend/generated/api.schemas.ts
+++ b/products/ai_observability/frontend/generated/api.schemas.ts
@@ -1515,6 +1515,85 @@ export interface TraceEvaluationResultsApi {
summary: TraceEvaluationSummaryApi
}
+export interface TraceExportCreateApi {
+ /** When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table. */
+ timestamp_hint?: string
+}
+
+export type ExportStatusEnumApi = (typeof ExportStatusEnumApi)[keyof typeof ExportStatusEnumApi]
+
+export const ExportStatusEnumApi = {
+ Pending: 'pending',
+ Complete: 'complete',
+ Failed: 'failed',
+} as const
+
+export interface TraceExportApi {
+ /** The export id, used to read its status and download the file. */
+ id: number
+ /** Whether the file is still being written, ready, or failed. */
+ status: ExportStatusEnumApi
+ /** The name the downloaded JSON file gets. */
+ filename: string
+ /** When the export was requested. */
+ createdAt: string
+ /** When the file is deleted. */
+ expiresAfter: string | null
+ /** Why the export failed, null unless status is failed. */
+ exception: string | null
+}
+
+export interface TraceNodeMetadataApi {
+ provider: string | null
+ temperature: number | null
+ sessionId: string | null
+ promptName: string | null
+ promptVersion: number | null
+}
+
+export interface TraceNodeIOKeysApi {
+ input: string | null
+ output: string | null
+ tools: string | null
+}
+
+/**
+ * The event's properties as ingested, including its input and output values.
+ */
+export type TraceNodeEventApiProperties = { [key: string]: unknown }
+
+export interface TraceNodeEventApi {
+ name: string
+ uuid: string
+ timestamp: string
+ /** The event's properties as ingested, including its input and output values. */
+ properties: TraceNodeEventApiProperties
+ /** Which keys of `properties` hold the node's input, output and tools, or null when it has none. */
+ ioKeys: TraceNodeIOKeysApi
+}
+
+export interface TraceNodeDetailApi {
+ id: string
+ kind: TraceNodeKindEnumApi
+ error: string | null
+ metadata: TraceNodeMetadataApi
+ event: TraceNodeEventApi | null
+}
+
+export interface TraceExportFileApi {
+ /** The trace as the trace endpoint returns it. */
+ trace: TraceApi
+ /** True when the trace has more events than an export reads. The file then holds the earliest events only, and leaves out the later steps. */
+ truncated: boolean
+ /** Every node with its event properties as ingested, inputs and outputs included: the root first, then the tree in pre-order. */
+ nodes: TraceNodeDetailApi[]
+}
+
+export interface TraceExportErrorApi {
+ /** Why the file cannot be downloaded yet. */
+ detail: string
+}
+
export interface TraceFeedbackScoreApi {
id: string
name: string | null
@@ -1629,43 +1708,6 @@ export interface TraceFeedbackApi {
summary: TraceFeedbackSummaryApi
}
-export interface TraceNodeMetadataApi {
- provider: string | null
- temperature: number | null
- sessionId: string | null
- promptName: string | null
- promptVersion: number | null
-}
-
-export interface TraceNodeIOKeysApi {
- input: string | null
- output: string | null
- tools: string | null
-}
-
-/**
- * The event's properties as ingested, including its input and output values.
- */
-export type TraceNodeEventApiProperties = { [key: string]: unknown }
-
-export interface TraceNodeEventApi {
- name: string
- uuid: string
- timestamp: string
- /** The event's properties as ingested, including its input and output values. */
- properties: TraceNodeEventApiProperties
- /** Which keys of `properties` hold the node's input, output and tools, or null when it has none. */
- ioKeys: TraceNodeIOKeysApi
-}
-
-export interface TraceNodeDetailApi {
- id: string
- kind: TraceNodeKindEnumApi
- error: string | null
- metadata: TraceNodeMetadataApi
- event: TraceNodeEventApi | null
-}
-
export interface TracePullRequestApi {
/** The owner of the pull request's repository. */
repoOwner: string
@@ -2060,20 +2102,11 @@ export interface DatasetExportCreateApi {
revision?: number
}
-export type DatasetExportReadStatusEnumApi =
- (typeof DatasetExportReadStatusEnumApi)[keyof typeof DatasetExportReadStatusEnumApi]
-
-export const DatasetExportReadStatusEnumApi = {
- Pending: 'pending',
- Complete: 'complete',
- Failed: 'failed',
-} as const
-
export interface DatasetExportReadApi {
/** Export ID used to check status and download the file. */
readonly id: number
/** Current export state: pending, complete, or failed. */
- readonly status: DatasetExportReadStatusEnumApi
+ readonly status: ExportStatusEnumApi
/** Immutable dataset revision included in the export. */
readonly dataset_revision: number
/** Generated JSONL filename. */
diff --git a/products/ai_observability/frontend/generated/api.ts b/products/ai_observability/frontend/generated/api.ts
index f554149f0054..ec03e69d9f85 100644
--- a/products/ai_observability/frontend/generated/api.ts
+++ b/products/ai_observability/frontend/generated/api.ts
@@ -156,6 +156,9 @@ import type {
TraceApi,
TraceClustersApi,
TraceEvaluationResultsApi,
+ TraceExportApi,
+ TraceExportCreateApi,
+ TraceExportFileApi,
TraceFeedbackApi,
TraceNodeDetailApi,
TracePullRequestLookupApi,
@@ -747,6 +750,65 @@ export const aiObservabilityTracesEvaluationsRetrieve = async (
})
}
+export const getAiObservabilityTracesExportsCreateUrl = (projectId: string, id: string) => {
+ return `/api/projects/${projectId}/ai_observability/traces/${id}/exports/`
+}
+
+/**
+ * Starts writing the trace and every node, inputs and outputs included, to a JSON file. Poll the export until it completes, then download it.
+ */
+export const aiObservabilityTracesExportsCreate = async (
+ projectId: string,
+ id: string,
+ traceExportCreateApi?: TraceExportCreateApi,
+ options?: RequestInit
+): Promise<TraceExportApi> => {
+ return apiMutator<TraceExportApi>(getAiObservabilityTracesExportsCreateUrl(projectId, id), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(traceExportCreateApi),
+ })
+}
+
+export const getAiObservabilityTracesExportsRetrieveUrl = (projectId: string, id: string, exportId: number) => {
+ return `/api/projects/${projectId}/ai_observability/traces/${id}/exports/${exportId}/`
+}
+
+/**
+ * The state of one of your exports of this trace.
+ */
+export const aiObservabilityTracesExportsRetrieve = async (
+ projectId: string,
+ id: string,
+ exportId: number,
+ options?: RequestInit
+): Promise<TraceExportApi> => {
+ return apiMutator<TraceExportApi>(getAiObservabilityTracesExportsRetrieveUrl(projectId, id, exportId), {
+ ...options,
+ method: 'GET',
+ })
+}
+
+export const getAiObservabilityTracesExportsContentRetrieveUrl = (projectId: string, id: string, exportId: number) => {
+ return `/api/projects/${projectId}/ai_observability/traces/${id}/exports/${exportId}/content/`
+}
+
+/**
+ * Downloads a completed export as a JSON file.
+ */
+export const aiObservabilityTracesExportsContentRetrieve = async (
+ projectId: string,
+ id: string,
+ exportId: number,
+ options?: RequestInit
+): Promise<TraceExportFileApi> => {
+ return apiMutator<TraceExportFileApi>(getAiObservabilityTracesExportsContentRetrieveUrl(projectId, id, exportId), {
+ ...options,
+ method: 'GET',
+ })
+}
+
export const getAiObservabilityTracesFeedbackRetrieveUrl = (
projectId: string,
id: string,
diff --git a/products/ai_observability/frontend/generated/api.zod.ts b/products/ai_observability/frontend/generated/api.zod.ts
index 477a9fa04acc..fc02f820d837 100644
--- a/products/ai_observability/frontend/generated/api.zod.ts
+++ b/products/ai_observability/frontend/generated/api.zod.ts
@@ -310,6 +310,18 @@ export const AiObservabilityOfflineExperimentsUploadCreateBody = /* @__PURE__ */
.describe('One to 1,000 unique item\/scorer-version results. The entire request commits atomically.'),
})
+/**
+ * Starts writing the trace and every node, inputs and outputs included, to a JSON file. Poll the export until it completes, then download it.
+ */
+export const AiObservabilityTracesExportsCreateBody = /* @__PURE__ */ zod.object({
+ timestamp_hint: zod.iso
+ .datetime({ offset: true })
+ .optional()
+ .describe(
+ 'When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table.'
+ ),
+})
+
/**
* Request an AI summary of the trace. A ready summary is returned as is unless `regenerate` is set; otherwise a job starts writing one, or the request joins the job already writing it.
*/
diff --git a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx b/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
index db07f62ecedc..b2f5c4594d6d 100644
--- a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
+++ b/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
@@ -4,6 +4,7 @@ import { aiObservabilityTraceLogic } from '../../aiObservabilityTraceLogic'
import { SaveToDatasetButton } from '../../datasets/SaveToDatasetButton'
import { traceViewAdapterLogic, traceViewAdapterLogicValues } from './adapter/traceViewAdapterLogic'
import { TraceView, TraceViewProps, TraceViewReadyProps } from './components/TraceView'
+import { traceExportLogic } from './traceExportLogic'
import { FeedbackEntry, MatchDirection, NodeDetailTab, SummaryItemKind, TraceMode } from './types'
type ReadyValues = Pick<
@@ -36,7 +37,7 @@ type ReadyValues = Pick<
| 'feedbackCountByNodeId'
| 'feedbackMode'
| 'selectedStepFeedback'
->
+> & { traceExportLoading: boolean }
interface ReadyActions {
setMode: (mode: TraceMode) => void
@@ -45,6 +46,7 @@ interface ReadyActions {
setDetailTab: (tab: NodeDetailTab) => void
viewInThread: () => void
prefetchNode: (id: string) => void
+ exportTrace: () => void
showFailingEvals: () => void
setQuery: (query: string) => void
stepMatch: (direction: MatchDirection) => void
@@ -61,7 +63,10 @@ function toReadyProps(values: ReadyValues, actions: ReadyActions): TraceViewRead
return null
}
return {
- header: values.header,
+ header: {
+ ...values.header,
+ exportAction: { loading: values.traceExportLoading, onExport: actions.exportTrace },
+ },
summary: {
...values.summary,
clusters: values.clustersChip,
@@ -119,7 +124,8 @@ function toReadyProps(values: ReadyValues, actions: ReadyActions): TraceViewRead
export function TraceScene(): JSX.Element {
const { traceId, dateRange } = useValues(aiObservabilityTraceLogic)
- const logic = traceViewAdapterLogic({ traceId, timestampHint: dateRange?.dateFrom ?? null })
+ const logicProps = { traceId, timestampHint: dateRange?.dateFrom ?? null }
+ const logic = traceViewAdapterLogic(logicProps)
// Every kea value getter is a hook, so read them all on every render, whatever the status.
const {
status,
@@ -155,6 +161,9 @@ export function TraceScene(): JSX.Element {
selectedStepFeedback,
} = useValues(logic)
const actions = useActions(logic)
+ const exportLogic = traceExportLogic(logicProps)
+ const { traceExportLoading } = useValues(exportLogic)
+ const { exportTrace } = useActions(exportLogic)
const readyProps =
status === 'ready'
@@ -188,8 +197,9 @@ export function TraceScene(): JSX.Element {
feedbackCountByNodeId,
feedbackMode,
selectedStepFeedback,
+ traceExportLoading,
},
- actions
+ { ...actions, exportTrace }
)
: null
diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
index fd94a31f1d8f..d31175fe6c01 100644
--- a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
@@ -44,6 +44,7 @@ const EVALUATIONS_URL = '/api/projects/:team_id/ai_observability/traces/:id/eval
const CLUSTERS_URL = '/api/projects/:team_id/ai_observability/traces/:id/clusters/'
const FEEDBACK_URL = '/api/projects/:team_id/ai_observability/traces/:id/feedback/'
const DATASETS_URL = '/api/projects/:team_id/datasets/'
+const EXPORT_URL = '/api/projects/:team_id/ai_observability/traces/:id/exports/'
const PULL_REQUEST_URL = '/api/projects/:team_id/ai_observability/traces/:id/pull_request/'
const SEARCH_URL = '/api/projects/:team_id/ai_observability/traces/:id/search/'
const SUMMARY_URL = '/api/projects/:team_id/ai_observability/traces/:id/summary/'
@@ -294,6 +295,45 @@ describe('TraceScene', () => {
}
)
+ it('exports the trace with its time and shows the button as busy until the export starts', async () => {
+ let releaseExport = (): void => {}
+ const exportStarted = new Promise<void>((resolve) => {
+ releaseExport = resolve
+ })
+ const exportBodies: unknown[] = []
+ useMocks({
+ post: {
+ [EXPORT_URL]: async ({ request }) => {
+ exportBodies.push(await request.json())
+ await exportStarted
+ return [
+ 201,
+ {
+ id: 7,
+ status: 'pending',
+ filename: 'trace-1.json',
+ createdAt: '2026-09-01T10:20:00Z',
+ expiresAfter: null,
+ exception: null,
+ },
+ ]
+ },
+ },
+ })
+ const { findByText } = renderNewView()
+ const button = (await findByText('Export')).closest('button')
+ if (!button) {
+ throw new Error('expected the export action to render as a button')
+ }
+
+ fireEvent.click(button)
+
+ await waitFor(() => expect(exportBodies).toEqual([{ timestamp_hint: '2026-09-01T10:15:00Z' }]))
+ expect(button.classList.contains('LemonButton--loading')).toBe(true)
+ releaseExport()
+ await waitFor(() => expect(button.classList.contains('LemonButton--loading')).toBe(false))
+ })
+
it.each([true, false])('offers add to dataset on the step only when datasets are on (%s)', async (enabled) => {
const { findByText, queryByText } = renderNewView({ [DATASETS_FLAG]: enabled })
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceExportButton.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceExportButton.tsx
new file mode 100644
index 000000000000..9dcb05b301fa
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceExportButton.tsx
@@ -0,0 +1,23 @@
+import { IconDownload } from '@posthog/icons'
+import { LemonButton } from '@posthog/lemon-ui'
+
+export interface TraceExportButtonProps {
+ loading: boolean
+ onExport: () => void
+}
+
+export function TraceExportButton({ loading, onExport }: TraceExportButtonProps): JSX.Element {
+ return (
+ <LemonButton
+ size="small"
+ type="secondary"
+ icon={<IconDownload />}
+ loading={loading}
+ onClick={onExport}
+ tooltip="Export this trace as a JSON file"
+ data-attr="trace-view-export"
+ >
+ Export
+ </LemonButton>
+ )
+}
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceHeader.stories.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceHeader.stories.tsx
index f14900753333..695361e98123 100644
--- a/products/ai_observability/frontend/redesign/trace/components/TraceHeader.stories.tsx
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceHeader.stories.tsx
@@ -18,8 +18,16 @@ export default meta
type Story = StoryObj<typeof TraceHeader>
+const exportAction = { loading: false, onExport: () => {} }
+
export const Default: Story = {}
export const Errored: Story = { args: { hasError: true } }
+export const WithExport: Story = { args: { exportAction } }
+export const ExportInProgress: Story = {
+ args: { exportAction: { ...exportAction, loading: true } },
+ // The busy button's spinner is the state this story shows, so the snapshot must not wait for it to go.
+ parameters: { testOptions: { waitForLoadersToDisappear: false } },
+}
export const WithSearch: Story = {
args: {
search: {
@@ -35,6 +43,6 @@ export const WithSearch: Story = {
},
}
export const Narrow: Story = {
- args: { name: 'a-very-long-trace-name-that-should-truncate-cleanly' },
+ args: { name: 'a-very-long-trace-name-that-should-truncate-cleanly', exportAction },
decorators: [withWidth(360)],
}
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceHeader.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceHeader.tsx
index 21c37fc0c6aa..fa20e4821068 100644
--- a/products/ai_observability/frontend/redesign/trace/components/TraceHeader.tsx
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceHeader.tsx
@@ -2,6 +2,7 @@ import { IconArrowLeft } from '@posthog/icons'
import { LemonButton } from '@posthog/lemon-ui'
import { LabeledLink } from '../types'
+import { TraceExportButton, TraceExportButtonProps } from './TraceExportButton'
import { TraceNeighbourLinks } from './TraceNeighbourLinks'
import { TraceSearchBox, TraceSearchBoxProps } from './TraceSearchBox'
import { TraceStatusBadge } from './TraceStatusBadge'
@@ -13,6 +14,7 @@ export interface TraceHeaderProps {
newerHref: string | null
backLink: LabeledLink
search?: TraceSearchBoxProps | null
+ exportAction?: TraceExportButtonProps
}
export function TraceHeader({
@@ -22,6 +24,7 @@ export function TraceHeader({
newerHref,
backLink,
search = null,
+ exportAction,
}: TraceHeaderProps): JSX.Element {
return (
<header className="flex flex-wrap items-center gap-2">
@@ -37,6 +40,7 @@ export function TraceHeader({
<TraceStatusBadge hasError={hasError} />
<div className="ml-auto flex min-w-0 flex-wrap items-center gap-2">
{search ? <TraceSearchBox {...search} /> : null}
+ {exportAction ? <TraceExportButton {...exportAction} /> : null}
<TraceNeighbourLinks olderHref={olderHref} newerHref={newerHref} />
</div>
</header>
diff --git a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
index a53e88c8c20a..f8fbf0661b26 100644
--- a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
+++ b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
@@ -383,6 +383,7 @@ export const FIXTURE_TRACE: SampleTraceFixture = {
olderHref: '/older',
newerHref: '/newer',
backLink: { label: 'Back to traces', href: '/traces' },
+ exportAction: { loading: false, onExport: () => {} },
},
summary: {
traceId: '3f9c2a71-5b8e-4d0f-a1c2-7e6d5b4a3c21',
diff --git a/products/ai_observability/frontend/redesign/trace/traceExportLogic.test.ts b/products/ai_observability/frontend/redesign/trace/traceExportLogic.test.ts
new file mode 100644
index 000000000000..4dcd25ddc46f
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/traceExportLogic.test.ts
@@ -0,0 +1,116 @@
+import { expectLogic } from 'kea-test-utils'
+
+import { exportsLogic } from 'lib/components/ExportButton/exportsLogic'
+import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
+
+import { useMocks } from '~/mocks/jest'
+import { initKeaTests } from '~/test/init'
+
+import type { TraceExportApi } from '../../generated/api.schemas'
+import { makeTraceResource } from './adapter/testFixtures'
+import { toExportedAsset, traceExportLogic } from './traceExportLogic'
+import { traceViewLogic } from './traceViewLogic'
+
+const TRACE_URL = '/api/projects/:team_id/ai_observability/traces/:id/'
+const EXPORT_URL = '/api/projects/:team_id/ai_observability/traces/:id/exports/'
+const EXPORT_STATUS_URL = '/api/projects/:team_id/ai_observability/traces/:id/exports/:export_id/'
+
+function makeTraceExport(overrides: Partial<TraceExportApi> = {}): TraceExportApi {
+ return {
+ id: 7,
+ status: 'pending',
+ filename: 'trace-1-2026-09-01-101500.json',
+ createdAt: '2026-09-01T10:20:00Z',
+ expiresAfter: '2026-09-08T10:20:00Z',
+ exception: null,
+ ...overrides,
+ }
+}
+
+describe('traceExportLogic', () => {
+ const props = { traceId: 'trace-1', timestampHint: null }
+ let createdExport: TraceExportApi = makeTraceExport()
+ let exportBodies: unknown[] = []
+ let statusRequests = 0
+
+ beforeEach(() => {
+ createdExport = makeTraceExport()
+ exportBodies = []
+ statusRequests = 0
+ useMocks({
+ get: {
+ [TRACE_URL]: () => [200, makeTraceResource()],
+ '/api/projects/:team_id/ai_observability/traces/:id/evaluations/': () => [200, { results: [] }],
+ [EXPORT_STATUS_URL]: () => {
+ statusRequests += 1
+ return [200, makeTraceExport({ status: 'complete' })]
+ },
+ },
+ post: {
+ [EXPORT_URL]: async ({ request }) => {
+ exportBodies.push(await request.json())
+ return [201, createdExport]
+ },
+ },
+ })
+ initKeaTests()
+ jest.spyOn(lemonToast, 'info').mockImplementation(() => 'toast')
+ jest.spyOn(lemonToast, 'error').mockImplementation(() => 'toast')
+ })
+
+ afterEach(() => {
+ jest.restoreAllMocks()
+ })
+
+ test.each([
+ ['pending', makeTraceExport(), { has_content: false, exception: undefined }],
+ ['complete', makeTraceExport({ status: 'complete' }), { has_content: true, exception: undefined }],
+ ['failed', makeTraceExport({ status: 'failed', exception: 'Boom' }), { has_content: false, exception: 'Boom' }],
+ ])('toExportedAsset maps a %s export', (_status, traceExport, expected) => {
+ expect(toExportedAsset(traceExport)).toMatchObject({ id: 7, export_format: 'application/json', ...expected })
+ })
+
+ test('exportTrace sends the trace time and hands the export to the exports panel', async () => {
+ exportsLogic.mount()
+ await expectLogic(traceViewLogic(props), () => {
+ traceViewLogic(props).mount()
+ }).toFinishAllListeners()
+ const logic = traceExportLogic(props)
+ logic.mount()
+ const tracked: ReturnType<typeof exportsLogic.actionCreators.trackExport>['payload'][] = []
+
+ await expectLogic(logic, () => logic.actions.exportTrace()).toDispatchActions([
+ 'exportTraceSuccess',
+ (action) => {
+ const isTrackExport = action.type === exportsLogic.actionTypes.trackExport
+ if (isTrackExport) {
+ tracked.push({
+ exportedAsset: action.payload.exportedAsset,
+ fetchLatest: action.payload.fetchLatest,
+ })
+ }
+ return isTrackExport
+ },
+ ])
+
+ expect(exportBodies).toEqual([{ timestamp_hint: '2026-09-01T10:15:00Z' }])
+ const [{ exportedAsset, fetchLatest }] = tracked
+ expect(exportedAsset).toEqual(toExportedAsset(createdExport))
+ await expect(fetchLatest?.()).resolves.toMatchObject({ id: 7, has_content: true })
+ expect(statusRequests).toBe(1)
+ expect(lemonToast.info).toHaveBeenCalledTimes(1)
+ })
+
+ test('an export that failed to start shows its reason and is not tracked', async () => {
+ createdExport = makeTraceExport({ status: 'failed', exception: 'The export could not be started. Try again.' })
+ exportsLogic.mount()
+ const logic = traceExportLogic(props)
+ logic.mount()
+
+ await expectLogic(logic, () => logic.actions.exportTrace())
+ .toDispatchActions(['exportTraceSuccess'])
+ .toNotHaveDispatchedActions([exportsLogic.actionTypes.trackExport])
+
+ expect(lemonToast.error).toHaveBeenCalledWith('The export could not be started. Try again.')
+ })
+})
diff --git a/products/ai_observability/frontend/redesign/trace/traceExportLogic.ts b/products/ai_observability/frontend/redesign/trace/traceExportLogic.ts
new file mode 100644
index 000000000000..820f0307ab76
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/traceExportLogic.ts
@@ -0,0 +1,116 @@
+import { MakeLogicType, connect, kea, key, listeners, path, props } from 'kea'
+import { loaders } from 'kea-loaders'
+
+import { ApiConfig } from 'lib/api'
+import { exportsLogic } from 'lib/components/ExportButton/exportsLogic'
+import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
+
+import { ExportedAssetType, ExporterFormat } from '~/types'
+
+import { aiObservabilityTracesExportsCreate, aiObservabilityTracesExportsRetrieve } from '../../generated/api'
+import { ExportStatusEnumApi, type TraceExportApi } from '../../generated/api.schemas'
+import { encodeTraceIdSegment } from './traceIdSegment'
+import { traceViewLogic } from './traceViewLogic'
+
+export interface TraceExportLogicProps {
+ traceId: string
+ timestampHint: string | null
+}
+
+export function toExportedAsset(traceExport: TraceExportApi): ExportedAssetType {
+ return {
+ id: traceExport.id,
+ export_format: ExporterFormat.JSON,
+ has_content: traceExport.status === ExportStatusEnumApi.Complete,
+ filename: traceExport.filename,
+ created_at: traceExport.createdAt,
+ expires_after: traceExport.expiresAfter ?? undefined,
+ exception: traceExport.status === ExportStatusEnumApi.Failed ? (traceExport.exception ?? undefined) : undefined,
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceExportLogicValues {
+ createdAt: string | null // traceViewLogic
+ traceExport: TraceExportApi | null
+ traceExportLoading: boolean
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceExportLogicActions {
+ trackExport: (
+ exportedAsset: ExportedAssetType,
+ fetchLatest?: import('lib/components/ExportButton/exportsLogic').ExportStatusFetcher | undefined
+ ) => {
+ exportedAsset: ExportedAssetType
+ fetchLatest: import('lib/components/ExportButton/exportsLogic').ExportStatusFetcher | undefined
+ } // exportsLogic
+ exportTrace: () => any
+ exportTraceFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ exportTraceSuccess: (
+ traceExport: TraceExportApi,
+ payload?: any
+ ) => {
+ traceExport: TraceExportApi
+ payload?: any
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceExportLogicMeta {
+ key: string
+}
+
+export type traceExportLogicType = MakeLogicType<
+ traceExportLogicValues,
+ traceExportLogicActions,
+ TraceExportLogicProps,
+ traceExportLogicMeta
+>
+
+export const traceExportLogic = kea<traceExportLogicType>([
+ props({} as TraceExportLogicProps),
+ key((props) => props.traceId),
+ path((key) => ['products', 'ai_observability', 'frontend', 'redesign', 'trace', 'traceExportLogic', key]),
+ connect((props: TraceExportLogicProps) => ({
+ values: [traceViewLogic(props), ['createdAt']],
+ actions: [exportsLogic, ['trackExport']],
+ })),
+ loaders(({ props, values }) => ({
+ traceExport: [
+ null as TraceExportApi | null,
+ {
+ exportTrace: async (): Promise<TraceExportApi> =>
+ await aiObservabilityTracesExportsCreate(
+ String(ApiConfig.getCurrentProjectId()),
+ encodeTraceIdSegment(props.traceId),
+ values.createdAt ? { timestamp_hint: values.createdAt } : {}
+ ),
+ },
+ ],
+ })),
+ listeners(({ actions, props }) => ({
+ exportTraceSuccess: ({ traceExport }) => {
+ if (traceExport.status === ExportStatusEnumApi.Failed) {
+ lemonToast.error(traceExport.exception ?? "Couldn't export this trace. Try again.")
+ return
+ }
+ actions.trackExport(toExportedAsset(traceExport), async () =>
+ toExportedAsset(
+ await aiObservabilityTracesExportsRetrieve(
+ String(ApiConfig.getCurrentProjectId()),
+ encodeTraceIdSegment(props.traceId),
+ traceExport.id
+ )
+ )
+ )
+ lemonToast.info("Exporting this trace. The file appears in Exports when it's ready.")
+ },
+ })),
+])
diff --git a/products/exports/backend/facade/api.py b/products/exports/backend/facade/api.py
index 6dc739181c6f..e7d0f90a036a 100644
--- a/products/exports/backend/facade/api.py
+++ b/products/exports/backend/facade/api.py
@@ -33,6 +33,7 @@ from products.exports.backend.models.exported_asset import (
save_content_from_file as _save_content_from_file,
)
from products.exports.backend.tasks.failure_handler import (
+ USER_QUERY_ERROR_NAMES,
InvalidExportContext as InvalidExportContext,
RetryableExportError as RetryableExportError,
)
@@ -102,6 +103,16 @@ def get_export_asset(*, team_id: int, asset_id: int) -> ExportedAsset | None:
return ExportedAsset.objects.filter(team_id=team_id, id=asset_id).first()
+def is_export_failure_final(*, exception_type: str | None, failure_type: str | None) -> bool:
+ """Whether a recorded export failure is final, rather than one the export workflow retries."""
+ # Every failure the workflow records carries a failure type, so one without it comes from a workflow that never
+ # started, and nothing will retry it.
+ if failure_type is None:
+ return True
+ # Mirrors the non-retryable error types of EXPORT_RETRY_POLICY.
+ return exception_type in USER_QUERY_ERROR_NAMES
+
+
def get_export_asset_content_response(*, asset: ExportedAsset, download: bool) -> HttpResponseBase:
return get_content_response(asset, download=download)
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 1aed61ba28b7..1ce2168a847c 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -37316,10 +37316,10 @@ export namespace Schemas {
detail: string;
}
- export type DatasetExportReadStatusEnum = typeof DatasetExportReadStatusEnum[keyof typeof DatasetExportReadStatusEnum];
+ export type ExportStatusEnum = typeof ExportStatusEnum[keyof typeof ExportStatusEnum];
- export const DatasetExportReadStatusEnum = {
+ export const ExportStatusEnum = {
Pending: 'pending',
Complete: 'complete',
Failed: 'failed',
@@ -37329,7 +37329,7 @@ export namespace Schemas {
/** Export ID used to check status and download the file. */
readonly id: number;
/** Current export state: pending, complete, or failed. */
- readonly status: DatasetExportReadStatusEnum;
+ readonly status: ExportStatusEnum;
/** Immutable dataset revision included in the export. */
readonly dataset_revision: number;
/** Generated JSONL filename. */
@@ -122415,6 +122415,77 @@ export namespace Schemas {
summary: TraceEvaluationSummary;
}
+ export interface TraceExport {
+ /** The export id, used to read its status and download the file. */
+ id: number;
+ /** Whether the file is still being written, ready, or failed. */
+ status: ExportStatusEnum;
+ /** The name the downloaded JSON file gets. */
+ filename: string;
+ /** When the export was requested. */
+ createdAt: string;
+ /** When the file is deleted. */
+ expiresAfter: string | null;
+ /** Why the export failed, null unless status is failed. */
+ exception: string | null;
+ }
+
+ export interface TraceExportCreate {
+ /** When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table. */
+ timestamp_hint?: string;
+ }
+
+ export interface TraceExportError {
+ /** Why the file cannot be downloaded yet. */
+ detail: string;
+ }
+
+ export interface TraceNodeMetadata {
+ provider: string | null;
+ temperature: number | null;
+ sessionId: string | null;
+ promptName: string | null;
+ promptVersion: number | null;
+ }
+
+ export interface TraceNodeIOKeys {
+ input: string | null;
+ output: string | null;
+ tools: string | null;
+ }
+
+ /**
+ * The event's properties as ingested, including its input and output values.
+ */
+ export type TraceNodeEventProperties = { [key: string]: unknown };
+
+ export interface TraceNodeEvent {
+ name: string;
+ uuid: string;
+ timestamp: string;
+ /** The event's properties as ingested, including its input and output values. */
+ properties: TraceNodeEventProperties;
+ /** Which keys of `properties` hold the node's input, output and tools, or null when it has none. */
+ ioKeys: TraceNodeIOKeys;
+ }
+
+ export interface TraceNodeDetail {
+ id: string;
+ kind: TraceNodeKindEnum;
+ error: string | null;
+ metadata: TraceNodeMetadata;
+ event: TraceNodeEvent | null;
+ }
+
+ export interface TraceExportFile {
+ /** The trace as the trace endpoint returns it. */
+ trace: Trace;
+ /** True when the trace has more events than an export reads. The file then holds the earliest events only, and leaves out the later steps. */
+ truncated: boolean;
+ /** Every node with its event properties as ingested, inputs and outputs included: the root first, then the tree in pre-order. */
+ nodes: TraceNodeDetail[];
+ }
+
export interface TraceFeedbackScore {
id: string;
name: string | null;
@@ -122513,43 +122584,6 @@ export namespace Schemas {
summary: TraceFeedbackSummary;
}
- export interface TraceNodeMetadata {
- provider: string | null;
- temperature: number | null;
- sessionId: string | null;
- promptName: string | null;
- promptVersion: number | null;
- }
-
- export interface TraceNodeIOKeys {
- input: string | null;
- output: string | null;
- tools: string | null;
- }
-
- /**
- * The event's properties as ingested, including its input and output values.
- */
- export type TraceNodeEventProperties = { [key: string]: unknown };
-
- export interface TraceNodeEvent {
- name: string;
- uuid: string;
- timestamp: string;
- /** The event's properties as ingested, including its input and output values. */
- properties: TraceNodeEventProperties;
- /** Which keys of `properties` hold the node's input, output and tools, or null when it has none. */
- ioKeys: TraceNodeIOKeys;
- }
-
- export interface TraceNodeDetail {
- id: string;
- kind: TraceNodeKindEnum;
- error: string | null;
- metadata: TraceNodeMetadata;
- event: TraceNodeEvent | null;
- }
-
export interface TracePullRequest {
/** The owner of the pull request's repository. */
repoOwner: string;