Skip to content

Add AI Observability traces video - #22424

Open
sarahxsanders wants to merge 4 commits into
masterfrom
learn-aio-traces-video
Open

sarahxsanders wants to merge 4 commits into
masterfrom
learn-aio-traces-video

Conversation

@sarahxsanders

@sarahxsanders sarahxsanders commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR adds the first Learn video, "Traces and generations". The video shows how to use a trace in AI Observability to debug an AI feature: the trip planner on Twig. It is the first video in a series. The next video (Evals) shows as "Coming soon".

The PR adds:

  • Learn TV, a video window at /learn/videos/aio-traces. It opens as a modal window, the same as the /demo video. The window toolbar says "Learn TV". The window shows the player, the video details, an "Up next" card, and a transcript.
  • /learn/videos, a new section of the Learn home. The "Videos" item in the Learn sidebar was "Coming soon". Now it links to this page.
  • /learn/ai-observability/videos, a new "Videos" item in the AI Observability Learn sidebar. The page has the same header style as the other hub pages, then a card for each video.
  • A "Watch the lesson" section on /learn/ai-observability. Its card opens the Learn TV window. The section shows when the hub's learnHub.pages includes 'videos'.

How the video is hosted

  • The MP4 is on Cloudinary (24.4 MB). No video file is in the repo. It is a HandBrake encode of the final edit: 1920×1080, constant 30 fps, H.264 (x264, Slow preset, High profile), 627 kbps two-pass video, and AAC stereo audio at about 103 kbps. The first upload was 49 MB. This encode is half that size, for mobile and slow connections.
  • The encode has the same 7,913 frames as the edit (263.767 s of video), so the frame-accurate captions stay in sync.
  • The poster is a frame of the same Cloudinary video (so_2,f_jpg).
  • The caption files are in static/learn/videos/ (aio-traces.en.vtt and aio-traces.en.srt). They are byte-for-byte copies of the reviewed files. Do not edit the caption text. The site serves the files from its own origin, so the caption track needs no CORS setup.

How captions and the transcript work

  • The <video> has one track: <track kind="captions" srclang="en" label="English" default>. The captions are not burned into the video.
  • The CC button sets the track to showing or hidden. Captions are on by default. This is the same as WistiaCustomPlayer, the only other captioned player on the site. The button has aria-pressed.
  • The transcript reads the cues from the same TextTrack. Thus the transcript always matches the captions, and nobody retypes the text. It follows playback on cuechange, also when the captions are off.
  • The transcript is real text in the DOM: a list of buttons. Each line seeks to its time and plays. The current line has aria-current and a highlight. The transcript box scrolls to keep the current line in view. The page does not scroll.
  • Some cues overlap on purpose (for example, [dramatic sting] inside a spoken line). The transcript lists the cues by start time and highlights all active cues.

Caption style (RoundHog) and a known issue

LearnTV/learnTV.css sets ::cue to RoundHog, sans-serif, with white text on an 80% black background. There is no font size, because browsers scale cues with the player.

Warning

Chrome does not show RoundHog in the captions. The ::cue rule applies: other values (color, Courier New, and the Squeak web font) show in the captions. But Chrome does not use the RoundHog font files in a cue. It falls back to Helvetica. The same files also fail with a new family name and with font-display: block. Thus the cause is in the font files, not in this CSS. The captions stay legible. Safari only partly supports ::cue styling, and the user's own caption settings in Safari and the operating system override these styles.

Review fixes

The PostHog Review bot found two problems. Both are fixed in cf89148:

  • Transcript auto-scroll. The transcript list is position: relative, so it is the offset parent of each line, and offsetTop is already inside the list. The old code also subtracted the offset of the list, so the box did not follow the current line. Now it uses offsetTop only.
  • No error state. If the MP4 did not load, the Play button did nothing, with no message. Now an onError handler shows "The video didn't load." and a Try again button. The button calls load() and then play().

The same commit also changes the colors to design-system tokens only:

  • The player and the details are in data-scheme="primary". Thus bg-primary and bg-accent are the panel (#FDFDF8) and chrome (#E5E7E0) neutrals of the Learn TV design. Before, the window's tertiary scheme made the chrome a darker grey (#C8CAC1).
  • The scrubber used a hard-coded color (#EFF7DE, from MediaPlayer). Now it uses bg-primary.
  • The cards used bg-white. Now they use the bg-light / dark:bg-dark tokens.
  • The transcript highlight used the site yellow (#F7A501), which is not a brand color. Now it uses brand Yellow: bg-brand-yellow-lighter (#FFDCA3) with a border-brand-yellow (#FFA81C) edge, as in the design. In dark mode, the background is brand Yellow at 20%.

Fixes from Edwin's review

Edwin's review comments are fixed in the last commit:

  • volume on video clicks. The cards on the hub Videos page now send learn_resource_selected with the hub's volume, the same as the other hub events.
  • One place decides which videos a hub has. LearnLanding no longer takes a video prop. It shows the "Watch the lesson" section when learnHub.pages includes 'videos', the same as the agent preview. "All videos" now opens the hub Videos page. ai-observability/index.tsx is the same as on master again.
  • Shared LearnVideosPage. The hub Videos page is now a shared component in components/Learn, like LivePlaygroundPage and AgentPromptsPage. Each product page passes its handle, name, and intro line.
  • LearnTVPage. Each video page file is now one line: <LearnTVPage slug="aio-traces" />. The component sets the SEO tags and the window title.
  • Window entries from the video list. App.tsx builds one entry for each video in LEARN_VIDEOS from a shared LEARN_TV_WINDOW, so a new video needs no new entry.
  • Standard toolbar. The page no longer shows its own title bar. The window uses the standard AppWindow toolbar, which says "Learn TV". The video title is not shown. It is the window's h1 for screen readers only.

The shared player controls (MediaPlayer and LearnTVPlayer) are in the stacked PR #22440. That change affects other pages, so it is not in this PR.

Accessibility

  • The window has a visually hidden h1 ("Traces and generations") for screen readers. The <video> has an aria-label.
  • All controls are native buttons or range inputs, with labels (Play, Mute, Volume, Seek, Back 10 seconds, Forward 10 seconds, Captions, Full screen). They work with the keyboard.
  • The video does not autoplay.

PR size

The diff has about 1,500 lines. The two caption files are 684 of these lines. The player (Player.tsx) is 329 lines.

PR tour

  1. src/components/Learn/LearnTV/: the player with the captions track and the control bar (Player.tsx), the transcript (Transcript.tsx), the Learn TV window (index.tsx), the video list (videos.ts), the card and the library (VideoCard.tsx, VideoLibrary.tsx), the caption style (learnTV.css), and README.md.
  2. src/pages/learn/videos/: the /learn/videos page, and one page file for each video. Each video page renders LearnTVPage (in LearnTV/LearnTVPage.tsx) with its slug.
  3. src/components/Learn/LearnVideosPage.tsx, src/pages/learn/ai-observability/videos.tsx, src/constants/pocketGuides.ts, and src/components/Products/ReaderViewProduct/buildProductMenuTabs.tsx: the shared hub Videos page, the AI Observability page file, and the sidebar item (a new videos hub page type).
  4. src/components/Learn/Home/index.tsx: enables the Videos sidebar item and adds the section.
  5. src/components/Learn/LearnLanding.tsx: the "Watch the lesson" section, for hubs whose learnHub.pages includes 'videos'. learnTracking.test.ts stubs the new imports.
  6. src/context/App.tsx: LEARN_TV_WINDOW, from the /demo entry, with a 1000px-tall window. appSettings gets one copy for each video in LEARN_VIDEOS.
  7. src/components/AppWindow/index.tsx: one condition. A /learn/* page with a modal window entry opens as a modal, not in LearnShell.
  8. static/learn/videos/: the caption files.
🔍 Reviewer's guide

Testing done

Check Command / method Result
Formatting Prettier on the changed files, and the pre-commit hooks (Prettier, ESLint, markdownlint) Pass
Nav and Learn tests pnpm test:navs 50 of 50 pass
Types tsc --noEmit, filtered to the changed files No new errors
Caption files cmp of the committed .vtt and .srt against the reviewed files Identical
Dev server pnpm start. Loaded /learn/videos, /learn/videos/aio-traces, /learn/ai-observability, /learn/ai-observability/videos All pages render
Captions and transcript Played the video in Chrome. Read the active cue and the highlighted transcript line At 0:04 and 0:12, the caption and the highlighted line match. 86 cues load
Console Headless Chrome on both sides of git stash. Compared the error sets One new warning on the Learn TV page: "two children with the same key" in AppWindow. Opening /demo the same way gives the same warning 5 times, so it comes from the modal window code, not from this PR
Review fix: transcript scroll Headless Chrome. Played from 2:00, then read the list position The box scrolls to 1,503px. The active line ("The results go to a second generation.") is in the visible part of the box, in light and dark
Review fix: error and retry Headless Chrome. Changed the video src to a missing file, then restored it and selected Try again The error shows. After the retry, the error goes away, readyState is 4, and the video plays
Edwin's fixes Headless Chrome on the dev server The hub Videos page renders from LearnVideosPage. The overview shows the section, and "All videos" opens /learn/ai-observability/videos. The window toolbar says "Learn TV", the hidden h1 is "Traces and generations", and the captions and transcript match at 2:00
volume on video clicks Headless Chrome with a recording window.posthog (dev loads no SDK) Both the hub Videos card and the overview card send learn_resource_selected with volume: "ai-observability"
Color tokens Headless Chrome. Read the computed background of each surface Title bar #D3DAC6, player chrome #E5E7E0, scrubber #FDFDF8, Up next header #E5E7E0 (light). Active transcript line #FFDCA3
Light and dark, narrow and wide Headless Chrome 157 at 640px and 1440px, both themes See the screenshots. A dark-mode contrast problem in the Learn TV headings is fixed

Not tested:

  • Production build (pnpm build): it uses more memory than this environment has. CI must pass before merge.
  • Safari and Firefox: I tested in Chrome only.
  • The bundled puppeteer Chromium (101) does not support container queries or H.264. Thus I took all screenshots with the system Chrome (157).
  • No GIF: this PR adds no animation. The transcript scroll follows playback. The screenshots show a highlighted line, not the motion.

Screenshots

Learn home: Videos

Before: /learn, with Videos as "Coming soon" in the sidebar. After: /learn/videos.

State Before After
Light, narrow window before-learn-videos-light-narrow after-learn-videos-light-narrow
Light, wide window before-learn-videos-light-wide after-learn-videos-light-wide
Dark, narrow window before-learn-videos-dark-narrow after-learn-videos-dark-narrow
Dark, wide window before-learn-videos-dark-wide after-learn-videos-dark-wide

AI Observability overview

The sidebar has a new Videos item. The page has a new "Watch the lesson" section.

State Before After
Light, narrow window before-aio-overview-light-narrow after-aio-overview-light-narrow
Light, wide window before-aio-overview-light-wide after-aio-overview-light-wide
Dark, narrow window before-aio-overview-dark-narrow after-aio-overview-dark-narrow
Dark, wide window before-aio-overview-dark-wide after-aio-overview-dark-wide

AI Observability: Videos (new page)

This page is new, so it has no before state.

State Before After
Light, narrow window New page after-aio-videos-light-narrow
Light, wide window New page after-aio-videos-light-wide
Dark, narrow window New page after-aio-videos-dark-narrow
Dark, wide window New page after-aio-videos-dark-wide

Learn TV window (new)

Opened from the card on /learn/videos. The video is at 0:12 with captions on. This page is new, so it has no before state.

State Before After
Light, narrow window New page after-learn-tv-light-narrow
Light, wide window New page after-learn-tv-light-wide
Dark, narrow window New page after-learn-tv-dark-narrow
Dark, wide window New page after-learn-tv-dark-wide

What to look at

  1. src/components/AppWindow/index.tsx:77: the new !appWindow?.modal condition. Every /learn/* page goes through this line. Today, only the Learn TV route has a modal entry, so other Learn pages do not change. But a future Learn route with a modal entry will lose the Learn sidebar shell. A mistake here can remove the sidebar from all Learn pages.
  2. src/context/App.tsx:1099: the window entries are built from LEARN_VIDEOS. App.tsx now imports components/Learn/LearnTV/videos.ts. That file has no imports, so it adds no import cycle. Also, the window is 1000px tall. On a short screen, the transcript is below the fold, and the user must scroll in the window. We will improve this layout in a later PR.
  3. src/components/Learn/LearnTV/Player.tsx:98: the transcript depends on the TextTrack cues. The track mode is hidden, not disabled, when captions are off, so that the cues stay loaded. If the mode becomes disabled, the transcript stops following playback.

🤖 Generated with Claude Code

Add a Learn TV window at /learn/videos/aio-traces for the first Learn
video. The MP4 plays from Cloudinary. A WebVTT captions track gives
closed captions, and the transcript reads the cues from the same track.

Add /learn/videos to the Learn home, a Videos page to the AI
Observability Learn hub, and a Watch the lesson section to its
overview.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sarahxsanders
sarahxsanders requested a review from a team as a code owner November 16, 2026 19:40
@sarahxsanders
sarahxsanders requested a review from a team November 16, 2026 19:40
@github-actions github-actions Bot added the website About the website (beyond just landing pages) label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 16, 2026 11:34PM

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Vale prose linter → found 0 errors, 16 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

src/components/Learn/Home/README.md — 0 errors, 2 warnings, 0 suggestions
Line Severity Message Rule
22:130 warning 'Cloudinary' is a possible misspelling. PostHogBase.Spelling
41:59 warning 'logomark' is a possible misspelling. PostHogBase.Spelling
src/components/Learn/LearnTV/README.md — 0 errors, 6 warnings, 0 suggestions
Line Severity Message Rule
1:3 warning 'Learn TV' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
20:40 warning 'Cloudinary' is a possible misspelling. PostHogBase.Spelling
20:170 warning 'kbps' is a possible misspelling. PostHogBase.Spelling
20:197 warning 'kbps' is a possible misspelling. PostHogBase.Spelling
30:15 warning 'Cloudinary' is a possible misspelling. PostHogBase.Spelling
47:173 warning 'Wistia' is a possible misspelling. PostHogBase.Spelling
src/components/Learn/README.md — 0 errors, 8 warnings, 0 suggestions
Line Severity Message Rule
9:245 warning 'subfolders' is a possible misspelling. PostHogBase.Spelling
20:28 warning 'subfolders' is a possible misspelling. PostHogBase.Spelling
20:91 warning 'subfolders' is a possible misspelling. PostHogBase.Spelling
43:878 warning 'subpage' is a possible misspelling. PostHogBase.Spelling
43:1031 warning 'Observability's' is a possible misspelling. PostHogBase.Spelling
50:362 warning 'scrollable' is a possible misspelling. PostHogBase.Spelling
52:290 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
53:36 warning 'Observability's' is a possible misspelling. PostHogBase.Spelling

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 0649149: 2 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Comment thread src/components/Learn/LearnTV/Player.tsx Resolved
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

12.22 MiB (+0.0 KiB / +0.0%)

Largest changed named chunks
Chunk Gzip Δ vs master
490bc41e476e65d6e70047bd978778ccbdbc6b56.js 454.7 KiB new
2461c6025d2bedd130ec0d6eb3c75cde5c20a8d5.js 127.1 KiB new
49b4b7068874fb7dcec1b52226ab714029d5d40a.js 60.9 KiB new
cfcc9e3efb38a26457e476c440637982c52f7652.js 49.0 KiB new
740846d0b8a7fcb004e98b07aa0e2a91e26d193f.js 23.3 KiB new
858b51590d8ef92822e962b83259d4be68a69b94.js 16.4 KiB new
441c3a0be63aa1ff9bc6a36ad076832610adfaaa.js 12.7 KiB new
8be3d8890c5fba754e08eb7eca041fd52c4e1cda.js 9.1 KiB new
09b656bd7a4481bbbe6e8eca67b9f946590279b6.js 8.6 KiB new
a72bfddde07afe02c6ec0fca22b2803e9f99743d.js 7.7 KiB new
96cbf8af3215f1af9f87be6f54513980acf10086.js 7.0 KiB new
e9b7ae57a002c73ed6618626c8f63ee768c64019.js 6.2 KiB new
8d525614c830d9089c2cccfc0be4b40e1f2dff56.js 5.2 KiB new
424cc2e9a3f191ec54a1c98fa2d69cf13e6e8f2e.js 4.4 KiB new
c146cdb000e87e2f1dc8d669b712722254a9ad28.js 4.3 KiB new

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 11.16 MiB (+8.3 KiB / +0.1%) report-only 1117
Largest modules in the app closure
Module Size
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 1023.6 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/puzzle.mjs 388.5 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/basketball-coach.mjs 337.4 KiB
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules 287.2 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules 273.1 KiB
./gatsby-browser.tsx + 60 modules 259.6 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-1.mjs 248.5 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules 240.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs 228.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs 221.7 KiB
./src/hooks/useProduct.ts + 18 modules 166.8 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

- Transcript: the list is the offset parent of each line, so do not
  subtract the list offset. The box now follows the active line.
- Player: show an error with a retry button when the MP4 does not
  load. Retry calls load() and then play().
- Colors: put the player and details in the primary scheme, so the
  surfaces use the panel and chrome neutrals of the design. Replace
  the hard-coded scrubber color with bg-primary, bg-white with
  bg-light, and the transcript highlight with brand Yellow tokens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed cf89148: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

Point the video and poster at compressed3 on Cloudinary. It is a
HandBrake x264 encode: 1080p, 30 fps, 627 kbps two-pass video, and
AAC audio. It is half the size of the first upload (49 MB), for mobile
and slow connections. It has the same 7,913 frames as the edit, so the
captions stay in sync.

Record the encode settings in the LearnTV README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sarahxsanders sarahxsanders changed the title Add Learn TV and the AI Observability traces video Add AI Observability traces video Nov 16, 2026

@edwinyjlim edwinyjlim left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comments on maintenance and reuse, inline below.

Comment thread src/components/Learn/LearnTV/Player.tsx Resolved
Comment thread src/components/Learn/LearnTV/index.tsx Resolved
Comment thread src/context/App.tsx Resolved
Comment thread src/pages/learn/videos/aio-traces.tsx Resolved

@edwinyjlim edwinyjlim left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📺

- Send the hub volume with video clicks on the hub Videos page.
- LearnLanding shows Watch the lesson when learnHub.pages includes
  'videos', and no longer takes a video prop. All videos opens the hub
  Videos page.
- Add a shared LearnVideosPage. The AI Observability page passes its
  handle, name, and intro line.
- Add LearnTVPage. Each video page file renders it with a slug.
- Build the Learn TV window entries in App.tsx from LEARN_VIDEOS.
- Use the standard window toolbar ("Learn TV"). Remove the custom title
  bar. The video title is a visually hidden h1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

website About the website (beyond just landing pages)

Projects

Status: New

Development

Successfully merging this pull request may close these issues.

2 participants