cAppDeveloper docsUse the diagnostic workspace
Debug Inspector is the application's own diagnostic workspace. It brings together navigation, console failures, request timing, declared service observations and runtime metadata so you can investigate the running package, rather than guessing from a screenshot of its UI.
Select uk.capp.sidecar.debug for the target application, then build and install the updated package. Desktop opens with Ctrl+Shift+D by default. Android has its own touch-oriented, full-screen inspector and launcher inside the usable system viewport.
The package declares desktop runtimes for Windows, Linux and macOS, plus a separate Android runtime. That declaration is not certification of every native target. Android does not receive the desktop inspector with mobile CSS layered over it.
Debug Inspector selection is independent of Android's application debug mode. It does not require android:debuggable=true. Enabling a build's debug flag is not a substitute for selecting the Sidecar, and selecting the Sidecar does not make the APK a debug build.
First useful diagnostic session
- Include Debug Inspector in the package you are investigating and open it once to confirm that it loaded.
- Check the capture settings relevant to the problem. Navigation, network, console and service capture are enabled by default; performance capture is opt-in.
- Return to the application and reproduce one bounded action, preferably with synthetic data. Note the order: user action, route change, request, response/failure and visible outcome.
- Reopen the inspector and examine the related events together. A failed browser request, a missing native service and an application exception are different faults.
- Export only the diagnostic material needed to explain the issue. Review it before sharing, even when redaction is enabled.
The retained buffer is finite: the default event limit is 2,000. Old events can be displaced. Capture a focused reproduction instead of expecting a complete permanent audit trail of a long-running app.
What the captures establish
| Capture | Useful for | Does not establish |
|---|---|---|
| Routes and navigation | Which app view was entered and when | A backend business operation completed |
| Console and uncaught failures | Application warnings, exceptions and context you explicitly logged | Complete visibility into every native process |
| Fetch/XMLHttpRequest timing and status | Which instrumented request failed or was slow | A valid business response merely because HTTP succeeded |
| Declared service observations | Linking app symptoms with available native/service state | Arbitrary process discovery or remote administration |
| Optional performance entries | Focused timing investigation | A full profiler or device-performance certification |
| Runtime, bundle and plan metadata | Identifying the package/configuration being tested | Successful installation or behaviour of a different package |
Instrumentation starts in the registered app/runtime surfaces. It cannot recover an event that happened before capture was active, nor inspect unrelated browser windows. Keep important application errors observable through the app's normal error handling as well.
Android opening and closing
The Android inspector covers the application while open; the product underlay is inert and scrolling is contained. Close it or use the supported Android Back action to return to the app. Header, tabs, content and footer should remain between the top and bottom guards when rotating the device or opening the keyboard.
The Android shell waits for its declared stylesheet and selected runtime plan before showing controls. A hidden launcher during startup can therefore be a readiness state. Persistent absence or a capp:debug-sidecar-failed event is a failure to investigate, not a reason to inject the desktop shell or disable the content security policy.
Rebuild/reinstall when changing the packaged runtime or target selection. Publishing the documentation website or changing a source folder does not update an already installed inspector.
Privacy and export discipline
Keep redactSecrets enabled. Sensitive header names, token-like query values and secret-shaped fields are redacted before retained events, but redaction is not a full data-loss prevention system. Ordinary messages, identifiers, URLs, request arguments and personal data may still identify a person or a private project.
Log safe event names and bounded non-sensitive context. Do not log passwords, tokens, seed phrases, full authentication replies or complete user records just because the inspector has a redaction setting. Review diagnostic JSON before attaching it to a public issue or sending it outside the team.
A capture toggle is a collection decision. Use only the categories needed for a reproduction, and decide deliberately whether diagnostics should ship in an end-user distribution. The Sidecar does not create a remote support port simply by being selected.
Public integration boundary
There is no portable Debug Inspector API for arbitrary process or filesystem inspection. Do not depend on its private instrumentation/controller objects or diagnostic globals as stable product contracts.
Use normal application logging and error handling for your own code, the supported runtime/data APIs for application operations, and Service Inspector for the UI controlling already declared services. Selecting Debug Inspector does not grant Agent permission to perform those operations.
Troubleshooting
| Symptom | Check and next step |
|---|---|
| No inspector in an installed app | Check the exact installed package's Sidecar selection and target, not only the current Library draft. |
| Android launcher remains hidden | Inspect bootstrap/style/plan readiness and the failure event; do not fall back to unstyled controls. |
| Missing network or console events | Check that category's capture setting and reproduce after instrumentation is active. |
| Old events have disappeared | The buffer is bounded. Export a focused capture and reproduce again. |
| Request fails while a service looks healthy | Separate browser/transport/authentication errors from process and health observations. |
| Export still contains sensitive context | Remove it before sharing and improve the application's own logging; do not rely solely on field-name redaction. |
For repeatable UI assertions use Test Runner. An inspector event is useful evidence, but it is not an automated pass/fail test of the product's postcondition.
Configuration reference
These are the selected package's configuration fields. String credential values and installation-specific defaults are never published here. A field's presence does not bypass its runtime policy.
| Field | Type | Meaning and constraints |
|---|---|---|
overlayDock | select | Overlay position. Choices: right, bottom, floating, fullscreen |
startup | select | Open behaviour. Choices: shortcut, remember, open |
retainEvents | number | Event buffer. Bounds: 250 to 20000 |
routeCapture | checkbox | Route events |
networkCapture | checkbox | Network events |
consoleCapture | checkbox | Console events |
serviceCapture | checkbox | Service events |
performanceCapture | checkbox | Performance samples |
redactSecrets | checkbox | Redact secrets |