zeekayandHanzo Dev
841ea1c0da
716 files rewritten, 30 renamed, same family mapping as the frontend pass.
Held back, and each for a reason rather than by oversight:
db_table values insights_hogfunction, insights_hogflow,
insights_hogfunctiontemplate, hogflow_templates.
Renaming a table is ALTER TABLE, so it ships as a
migration with the raw SQL in nodejs that names it.
hog_invocation_results a Datastore table with Kafka engine tables on it
products/review_hog the module path is the Django app path; moving it
moves app_label and every migration is recorded under
(app_label, name). That is the same history break as
renaming a migration file, one level up.
*/migrations/* five files, untouched
whogho an integration vendor
Checked: 395 of 397 changed Python files compile. The two that do not —
insightsql/database/database.py and temporal/schedule.py — fail identically at
origin/main under the same interpreter, because they use `type X = ...` and
`except*`, which need the 3.13 this repo pins and not the 3.9 doing the check.
Running the check against the original is what told those apart from a real
break.
Co-authored-by: Hanzo Dev <[email protected]>
5.1 KiB
Live Debugger
Live Debugger provides runtime inspection capabilities for Insights users by enabling breakpoints in production code. When a breakpoint is hit, the system captures local variables, stack traces, and execution context without interrupting the running application.
Related Projects
- https://github.com/Insights/scripttrace, a DTrace-inspired language for defining instrumentation scripts. It includes a Rust-based VM that can evaluate expressions within the context of the client application safely.
- https://github.com/Insights/libdebugger, a library for runtime instrumentation of Python code.
Flow
Insights UI User Application
───────────── ────────────────
│ │
│ (1) Create breakpoint │
▼ │
┌─────────┐ │
│ Postgres│ │
└─────────┘ │
│ │
│ (2) Fetch active breakpoints │
│ (Project API key) │
└─────────────────────────────────────────────────►│
│
│ (3) Breakpoint hit
│ Capture state
│
│ (4) Send event
┌───────────┐ │ $data_breakpoint_hit
│ Datastore│ ◄─────────────────────────────────────────┘
└───────────┘
│
│ (5) Query hits (InsightsQL)
▼
Insights UI
Architecture
The system consists of three components working together. The backend stores breakpoint definitions in PostgreSQL, associating each breakpoint with a team, repository, file, and line number. When instrumented code executes, it sends breakpoint hit events to Insights that are stored in Datastore for efficient querying. The frontend provides a GitHub repository browser where users can navigate source files, set breakpoints, and inspect captured runtime state.
Applications poll the external API using a Project API key to fetch active breakpoints for their repository. When code execution reaches a breakpoint line, the instrumentation layer captures the current state and sends it as a Insights event. The system supports conditional breakpoints through optional Python expressions that determine whether to capture state at a given location.
API Endpoints
The product exposes two primary endpoints. The /v1/environments/:team_id/live_debugger_breakpoints/ endpoint handles breakpoint management operations through standard CRUD methods. The /v1/environments/:team_id/live_debugger_breakpoints/active/ endpoint allows external applications to fetch enabled breakpoints using Project API key authentication, returning breakpoint configurations that applications use to instrument their code at runtime.
The /v1/environments/:team_id/live_debugger_breakpoints/breakpoint_hits/ endpoint queries Datastore for captured runtime state, retrieving events from the last hour with support for filtering by specific breakpoint and pagination. Each hit contains the captured variables, stack trace, timestamp, and execution context.
Data Model
Breakpoints are identified by the combination of team, repository, filename, and line number. Each breakpoint can be enabled or disabled and may include a condition expression. Breakpoint hits are stored as Insights events with the event name $data_breakpoint_hit containing properties for the breakpoint ID, file path, line number, function name, local variables, and stack trace.
The system enforces team isolation at both the database and API levels. Breakpoint queries automatically filter by team ID, and attempts to access breakpoints from other teams return 404 responses to prevent information disclosure.
Security Considerations
The external API uses Project API key authentication to allow runtime applications to fetch breakpoints without requiring user credentials. This enables server-side applications, background workers, and other headless processes to participate in debugging sessions. The API validates that breakpoint IDs belong to the requesting team before returning hit data, preventing cross-team data access through breakpoint ID enumeration.