The events subject handles client-side analytics by recording user interactions from the browser and sending them to GitHub's data pipeline. Events track anonymous usage data to help understand how users interact with docs.github.com and identify areas for improvement.

This subject is responsible for:

• Recording browser events (page views, clicks, searches, surveys, etc.)
• Validating event data against JSON schemas
• Sending events to Hydro (GitHub's data warehouse)
• Analyzing survey comments with sentiment analysis
• Providing React components for event tracking
• Server-side event endpoint (POST /events)

• middleware.ts - Express router handling POST /events endpoint, validates and publishes events
• lib/schema.ts - JSON Schema definitions for all event types using AJV validation
• components/events.ts - Client-side utilities for sending events from the browser

1. Browser sends POST /events request with event data
2. Middleware validates against JSON schema
3. If valid, event is sent to Hydro data warehouse
4. If invalid, validation error is logged (not sent to warehouse)

Supported event types (see EventType enum):

• page - Page view
• exit - User leaving page
• link - Link click
• search - Search query
• survey - Survey response

import { sendEvent } from '@/events/components/events'

sendEvent({
  type: 'link',
  link_url: 'https://example.com',
})

All events require a context object with:

• event_id (UUID)
• user (UUID) - Anonymous user identifier
• version - Schema version
• created - Timestamp
• path - Current page path
• Browser metadata (user agent, viewport size, etc.)

Each event type has additional required/optional fields defined in lib/schema.ts.

Test event validation locally:

npm run test -- src/events/tests

Test comment analysis:

tsx src/events/scripts/analyze-comment-cli.ts "This is a great article!"

• Browser events from client-side JavaScript
• Survey responses and comments
• User context (language, version, product, path)
• Browser metadata (user agent, viewport, etc.)

• Hydro API - GitHub's data warehouse
• AJV - JSON schema validation
• AI comment analysis service (internal)
• @/versions, @/products, @/languages - For enum validation

Schemas enforce:

• Required fields for each event type
• Enum values (languages, versions, products, tools)
• Format validation (UUID, date-time, URI)
• Additional properties not allowed

• Events sent to Hydro data warehouse
• Validation errors logged to Failbot (production)
• Survey sentiment analysis results

• src/observability - Error logging and monitoring
• src/versions - Version enum validation
• src/products - Product enum validation
• src/languages - Language enum validation
• src/tools - Tool enum validation

For detailed internal documentation about the data pipeline and Hydro, see the internal Docs Engineering repository.

• Team: Docs Engineering (code and analytics), Data Engineering (data pipeline)

• Survey comment sentiment analysis requires network call (adds latency)
• Event validation errors are deduplicated with LRU cache to prevent spam
• In production, events are fire-and-forget (don't wait for response)
• Validation errors sent to Hydro to track schema mismatches

1. Add event type to EventType enum in types.ts
2. Add type-specific properties to EventPropsByType in types.ts
3. Add schema definition to lib/schema.ts
4. Update warehouse schema (internal process)
5. Add client-side tracking code in components as needed
6. Test validation with unit tests

Survey responses with comments are analyzed for sentiment:

• Positive/negative/neutral rating assigned
• Language detection for comment text
• Results stored in survey_rating and survey_comment_language fields

• Validation errors appear in server logs
• Production validation errors sent to Hydro for tracking
• Use analyze-comment-cli.ts to test sentiment analysis locally