Insider documentation

Copy Markdown View Source

This is the index of Insider's reference documentation. The README is the short synopsis. The cheat sheet has the commands you use most, and the glossary defines the terms.

Contents

How to use this index

  • Find your task in one of the three tables below. Read only the section it names. A section runs from its heading to the next heading of the same or a higher level.
  • Use the anchors as stable references. Line numbers change with every edit, so this index does not give them.
  • The sizes are approximate line counts of the section, including its subsections. No linked section is longer than 150 lines. A test checks both.
  • Each topic file starts with links back to this index, the glossary and the cheat sheet, then its own contents list.
  • On a running node, the welcome document is the authority for the Insider that is loaded. Where it and these files differ, trust the welcome and file a doc_mismatch report.

Use Insider Live

Live observation of a running development, test or ci node. This is what the README describes.

If you need to …ReadSize
Run the commands you use mostCheat sheet~115 lines
Look up a termGlossary~265 lines
Install the CLI from Hex, or add Insider to your appInstall the CLI, Add Insider to your app~16 + ~22 lines
Make first contact with a node you startObserve a running node in five minutes~112 lines
Make first contact with a node you did not startAttach to a node you did not start, then Load Insider into the target~18 + ~29 lines
Know what the welcome document gives an agentWelcome document~67 lines
Find the commands for a symptomWelcome recipes~62 lines
Get the short operating contract for live observationLive observation guide~190 lines
Choose an Insider.Live function or start optionLive observation~109 lines
Know who may observe a node, and for how longEnvironment and ownership, Lease~17 + ~17 lines
Look up an observer flagObserver flag reference, Recording flags, Read flags~48 + ~27 + ~33 lines
Read without passing --sessionDefault session~13 lines
Understand an exit status or observer errorExit statuses and error codes~46 lines
Run several agents at onceSeveral agents at once: the escript, then Several agents on one session~14 + ~115 lines
Observe through Tidewave project_evalTidewave project_eval~31 lines
Stop a session and check what was cleaned upStop and check the cleanup receipt~37 lines
Pair with a programmer who acts in the appPairing marks, then Digest~41 + ~136 lines
Show the programmer you pair with a chart of the sessionPairing chart~46 lines
See what is wrong on the node right nowDigest~136 lines
Follow a digest hintDigest hints and text~71 lines
Hide anomalies you already know aboutKnown-normal baseline~33 lines
See how a series moved over timeSummary trends~76 lines
Pages hang, but each request looks fastRequest waits and bursts, then One-shot inspections~46 + ~136 lines
Investigate a stuck process or a growing mailboxOne-shot inspections, Process and ETS evidence~136 + ~116 lines
Read one request as a traceRead one request as a trace~80 lines
Keep a trace past evictionPin a trace~52 lines
See the values a GraphQL response returnedResponse values~42 lines
Find an N+1 or a repeated queryRepeated query shapes~49 lines
Follow an Oban jobOban jobs~17 lines
See everything one process or request didTimeline of a process or request~19 lines
Find who sent a GraphQL request or mutationGraphQL outcome, Kept mutation records~64 + ~37 lines
Find who changed an in-memory valueChanges of in-memory values~71 lines
See the arguments of calls to one functionCall traces~132 lines
Join a frontend's spans to the backend'sFrontend traces~56 lines
Record the node's OpenTelemetry spansOpenTelemetry spans and traces~90 lines
Find which Telemetry events a node emitsTelemetry discovery~88 lines
Read events without missing anyCursors and gaps~111 lines
Understand a gap or an empty readGaps, Filtered counts, Per-reader views~47 + ~20 + ~12 lines
Change what a running session recordsLive amendment~24 lines
Quiet a noisy development serverFilters, summaries, and views~108 lines
Know what each disclosure profile shows and withholdsWhat each profile shows and withholds~89 lines
Know how credentials are maskedCredential masking~82 lines
Know why something was refusedError codes, then the refusals guide~89 lines
Report a bug in InsiderAgent reports~118 lines
Explain the safety model to a personThe safety model guide~114 lines
Know where production stopsProduction boundary~21 lines

Lab and research

The Lab is a separate Mix project, published to Hex as insider_lab. Its tools and the Sentinel chain run only in development and disposable environments.

If you need to …ReadSize
Chase a flaky test, or run one repeatedlyFlaky tests: what Insider offers~32 lines
Find test-isolation candidatesAgent-requested ExUnit candidates~120 lines
Confirm a candidate with an oracleApplication-env oracle, Handler and global-state oracles, Oracle runner~93 + ~122 + ~78 lines
Check who may perform an operation, or a retry after a faultProbe-library oracles~72 lines
Drive mix insider or the Lab escriptLab CLI transport~84 lines
Check that a privacy corpus leaks nothingPrivacy corpus runner~56 lines
Understand clean-target reproductionCollector-to-Sentinel handoff, Confirmation and verification~81 + ~94 lines
Shrink or bisect a reproductionRegression and minimization, Bisection~63 + ~69 lines
Follow the offline repair chainProof workflow~127 lines
Check an incident capsule or its provenanceIncident capsules, Portable provenance~34 + ~14 lines
Run a supervised collector session in a host appSupervised collector sessions~111 lines
Know which detectors exist todayDetection goals~21 lines

Production readiness and development

Production readiness work grants no authority: staging and production observation stay denied.

If you need to …ReadSize
Understand how the parts fitArchitecture~140 lines
Know what is implemented todayCurrent status, Live observation status, Lab investigation status~42 + ~78 + ~59 lines
Know what the roadmap plansRoadmap~26 lines
Contribute codeChecks and gates and Repository layout, after AGENTS.md~49 + ~27 lines
Find load and soak evidenceSynthetic load and soak evidence~22 lines
Release a version to HexReleasing~98 lines

Files

FileWhat it holdsSize
Getting startedInstalling the CLI, the five-minute quick start, a node you did not start, the Tidewave variant, adding Insider to your app, repository setup, and a host AGENTS.md snippet.~207 lines
Cheat sheetThe most-used observer commands, by task.~115 lines
GlossaryTerms, and the ones that mean different things in Live, the Lab and the load harness.~265 lines
Insider Live: API and transportsFunctions and start options, environment, lease, cleanup receipt, Tidewave, and the observer node and its flags.~580 lines
Insider Live: sessions, readers and marksCursors and gaps, Recorder shares, subscriptions, several readers, amendment, handoff, marks, the pairing chart, and event time.~483 lines
Insider Live: digest, filters and trendsThe digest, its hints and baseline, summary trends, filters, summaries, views, and severity.~580 lines
Insider Live: processes, calls and TelemetryProcess and ETS rankings, one-shot inspections, call traces, changes of in-memory values, and Telemetry discovery.~585 lines
Insider Live: OpenTelemetry traces and GraphQLSpans, traces, query shapes, Oban jobs, pinned traces, response values, mutation records, timelines, request waits, the GraphQL outcome, and the OTLP receiver.~585 lines
Insider Live: welcome, reports and error codesThe welcome document and its recipes, agent reports, and the error-code vocabulary.~435 lines
Disclosure and safetyThe production boundary, profiles and what each withholds, rich rendering, credential masking, redaction, and non-goals.~390 lines
Collectors and detectorsThe signals Insider reads, supervised collector sessions, the system-event collector, detectors, contracts, polling, and the same-node diagnostic API.~450 lines
Lab: ExUnit candidates and oraclesThe candidate inventory, the value-free oracles, the oracle runner, probe-library oracles, and flaky tests.~545 lines
Lab: CLI transport and privacy corpusmix insider, the escript, acceptance hosts, the Recorder, collectors, ingress profiles, and the privacy corpus runner.~500 lines
Sentinel and the proof workflowConfirmation, verification, regression, minimization, bisection, the offline repair chain, and deduplication.~600 lines
Incident capsules and provenanceCapsules, provenance, and the inert observability trigger and export.~115 lines
ArchitecturePurpose and the intended loop, the trust boundary, module boundaries, and the production artifact boundary.~140 lines
DevelopmentRepository layout, checks and gates, load and soak evidence, documentation tooling, and releasing to Hex.~276 lines
Status and roadmapWhat is implemented, as tables, and the roadmap phases.~220 lines

Other documents