petrbouda/microscope

Turns a Jeffrey profile into concrete code changes in the current repository — maps the hottest CPU, wall-clock, allocation and blocking frames, the slowest traces, the waiting on locks and I/O, the database and HTTP work, and a heap dump's leak suspects to real source, recommends minimal behaviour-preserving edits, applies them on request and verifies with the tests and a re-profile. Use whenever the user asks what to change, optimise or fix based on a profile, JFR recording, flamegraph or trace, why an endpoint is slow and what to do about it, or a hotspot is known and the question is what to do about it.

Finds and analyses JVM recordings that live on the connector (the recording volume on an Azure file share, or in a local directory) rather than in a file the user has — the JFR recordings, heap dumps, application logs, GC logs and crash files a deployed application produced. Use whenever the user asks about what an environment recorded or wrote rather than about a file they have: production, staging, a named service, "the last hour", "since the deploy", "what the connector has", "why was prod slow this morning", "why did the pod's JVM die", "the exceptions in the service log". It locates the session, asks which interval matters, pulls in that part of the recording — or the one file that matters — and hands off to analyze-jfr or analyze-heap, or reads the log itself. For a recording file already on this machine, analyze-jfr applies directly.

Analyses the exceptions an application threw in a Jeffrey profile and traces each one to the code in the current repository that caused it — separates the application's throws (libraries included, so timeouts and connection resets stay) from the JVM's own class-loading and linking noise, finds where the application's code entered each throw, reads that source and recommends the smallest fix. Use whenever the user asks to analyse the exceptions or errors of an application, service or recording, why an application throws so much, what an exception storm or a burst of timeouts in a profile is caused by, whether exceptions are used as control flow, or names an exception class seen in a JFR recording or Microscope's Exceptions page.

Analyses a heap dump held by a running Jeffrey Microscope — what is holding the memory, what is leaking, which class loader survived a redeploy, where the waste is — starting from the catalogue or from a .hprof file Jeffrey has not seen yet. Use whenever the user asks what is holding memory, why the heap keeps growing, why the JVM ran out of memory, what is leaking, or mentions retained size, a dominator tree, GC roots, a heap dump or an .hprof file.

Analyses a JVM profile held by a running Jeffrey Microscope — CPU, wall-clock, allocation, lock contention, trace latency, and the machine underneath: garbage collection, safepoints, JIT compilation, threads, native memory, the container and the JVM's configuration. Starts from the catalogue or from a .jfr file Jeffrey has not seen yet. Use whenever the user asks why something is slow, where the time goes, what is allocating, why GC pauses are long, what is pausing the JVM, what the JIT compiler or deoptimisation is doing, which threads are burning CPU, why memory grows outside the heap, whether the container is throttling, what a JFR recording or flamegraph shows, or mentions a Jeffrey profile, a .jfr file or async-profiler output. For a heap dump or .hprof file, analyze-heap applies instead.

Compares two JVM profiles held by a running Jeffrey Microscope — a before and an after — using differential flamegraphs, to answer whether a change made the application slower, faster, or allocate more. Use whenever the user asks if a change regressed performance, what got slower or faster between two runs, to compare two recordings, benchmarks or branches, or mentions a baseline, a before/after or a performance regression. For a single profile, analyze-jfr applies instead; for a heap dump, analyze-heap.

Load before the first heap_executeQuery call, whichever skill is driving the analysis: the schema of a Jeffrey heap-dump index (class, instance, outbound_ref, class_instance_field, string_content, gc_root, dominator, retained_size) and the traps that return a wrong answer without an error — the string table is the name pool, not the String contents; outbound_ref.field_id counts the whole field layout; retained sizes need the current tree. Use for what the purpose-built heap tools do not answer: what objects' fields or strings hold across a class, a count or join they do not shape.

Explains what a running Jeffrey Microscope can investigate and how to get there — the areas a JFR recording or a heap dump can answer (CPU, wall-clock, allocation, locks, requests and outbound calls, the database, I/O, exceptions, GC and pauses, JIT, threads, native memory, the container, leaks, and a heap dump's contents, retention and waste), what each needs recorded, which skill takes each, and which profiles are here now. Use whenever the user asks what Jeffrey or Microscope can do, what they can investigate or ask, which areas there are, what to record so a question can be answered, how to start, or says "help" about Jeffrey, before any profile is chosen. For a profile already named with an open question, analyze-jfr's menu applies directly.

Load before the first jfr_executeQuery or jfr_queryEvents call, whichever skill is driving the analysis: the schema of a Jeffrey profile's JFR database (events, event_types, threads, stacktraces, frames), the field names per event type, and the traps that return a wrong answer without an error — events_raw's truncated fields, ->> binding tighter than casts, root-first stacks, the row cap. Use for what no flamegraph, trace, heap or jvm dashboard tool answers: how many distinct values a field takes, a distribution over time, a correlation between event types.

Runs this project under a profiler and analyses what comes out — a benchmark, a test, a load script or the application itself, recorded with JFR or async-profiler, imported into a running Jeffrey Microscope and handed to analyze-jfr. Use whenever the user wants to profile something that is not recorded yet: "profile this benchmark", "record a JFR while the tests run", "why is this slow" with no recording in hand, or when a hotspot needs measuring rather than guessing — and when they ask how to record what a recording lacks: which JFR settings or async-profiler events capture exception types, locks, allocation or wall-clock time, per JDK version ("how do I record the exception types next time").

Decides whether a change made this project slower, by profiling two revisions the same way and weighing them against each other — build and record each, import both into a running Jeffrey Microscope, then report what moved and by how much. Use when the user asks whether a commit, branch or pull request regressed performance, wants a before-and-after measured rather than argued, or suspects a slowdown appeared somewhere in a range of commits.

The shape and the evidence rules for any performance finding drawn from a Jeffrey Microscope profile — what a finding must carry before it is worth writing down, how a figure is quoted and against what denominator, what caps a claim at medium confidence, and how the questions a recording cannot answer are reported apart from the findings. Use whenever writing up an analysis, summarising an investigation, answering "what did you find", or handing conclusions to another person or agent — once analyze-jfr, analyze-heap, compare-jfr, regression-check or advise-jfr has done the reading.