Skip to content

Diagnostics

Jump to bottom
stud0709 edited this page Oct 21, 2026 · 10 revisions

Diagnostics

These tools and diagnostic subsystems enable the agent and developer to dive into details of log entries, runtime errors, and raw telemetry.

For sap_fetch_runtime_errors, a feed entry advertising only GUI navigation returns its retained summary with detail_status: "sap_gui_only" and available gui_uri. This applies to topmost: 1 and full: true; the response supplies summary evidence rather than a full dump. Ask the developer to inspect the GUI target when deeper details are needed. Supported HTTP detail representations remain available when advertised.

Successful sap_execute_request response text remains intact as an authorized working artifact, inline or in spillover files. Diagnostic and reporting copies are sanitized separately. Generic response expiry preserves named working artifacts and nested exports under their owning workflows.

Available MCP Tools

Tool Name Description
sap_fetch_application_log Fetches SAP Application Log headers and decoded messages. Select an exact log handle or number, or filter by object, subobject, external ID, user, or date/time. max_logs bounds the result.
sap_decompress_blob Decompresses SAP database BLOBs and cluster streams (e.g. from SOFFCONT1, REPOSRC, STXL, BALDAT) using SAP's proprietary LZC/LZH (DEFLATE with bit padding) compression format.
sap_fetch_runtime_errors Retrieves and parses ABAP Short Dumps (ST22). Returns recent crash summaries or detailed diagnostics including source extract and stack trace.
sap_fetch_spool Retrieves ABAP spool request metadata and formatted output lines with configurable windowing (line_offset, max_lines) and pagination.
sap_export_diagnostics Exports sanitized diagnostic logs and telemetry as a JSON or Markdown file for troubleshooting.
sap_verify_transport Verifies transport request status, tasks, object locks, and table keys in the SAP Transport Organizer.
sap_execute_local_sqlite Executes SQL queries against the local sap-bridge SQLite database (.sap_dev.db).
sap_file_report Files an anonymized incident report or developer handover for sap-dev tooling defects to GitHub Issues with optional workspace file attachments.
sap_search_issues Searches open and closed GitHub issues in the configured issue tracker to check for duplicates before filing reports. Supports text search and state filtering ('all', 'open', 'closed').

Workspace Telemetry

Use the Web Dashboard Diagnostics view or sap_bridge_status(view: "diagnostics") for health and recent activity. For focused local audit queries, use sap_execute_local_sqlite against the workspace's daemon, MCP, or ADT log tables. sap_export_diagnostics creates a sanitized JSON or Markdown copy when troubleshooting evidence needs to be shared. Inspect the exported copy before attaching it to an issue.

For Application Log investigations, use sap_fetch_application_log with the narrowest known identity or filters. An empty result includes an explanatory message; populated logs expose the technical message_type, message_class, and message_number alongside resolved text when available. Query filters work across ADT data-preview systems that limit the length of each query line.

Supply transport_request on every sap_verify_transport call. Omit object selectors for a request overview. To check one object within that request, add either its exact CTS target, for example {"pgmid":"R3TR","object":"TABU","obj_name":"ZTBL_CONFIG"}, or a staged source_file_path with a unique CTS mapping. pgmid is R3TR or LIMU; object is the four-character CTS recording code. The former object_type and object_name selectors are retired.

Offline & Disconnected System Diagnostics

In many enterprise environments, Production systems or external landscapes are disconnected from the agent workspace (e.g. only DEV and QA have bridge/ADT access, while PROD is firewalled or restricted).

Developers can capture diagnostic traces directly inside the disconnected SAP GUI session and supply the exported files to the AI agent. The agent parses the trace and cross-references the execution coordinates directly with the source code present in the connected DEV system.

Tool Selection: Which Trace to Use?

Diagnostic Goal Recommended Tool Role in Agent Analysis
Functional Bugs & Logic Flow
(IDoc failure, EWM WT creation quirks, unexpected branch) 		SAT (Runtime Analysis) Primary: Maps the exact chronological call tree (methods, functions, subroutines, BAdIs) down to the divergence point.
SQL Filters & Return Codes
(Missing customizing, DB return codes, optimizer scans) 		ST05 (Performance Trace) Complementary: Reveals runtime literal values (WHERE "FIELD" = 'VAL'), row counts, and return codes (0 vs 4/64).
Application Errors & Warnings
(Background jobs, batch processing, EWM strategies) 		SLG1 / BALM (Application Log) Precise: Provides technical message IDs (MSGID) and numbers (MSGNO) to locate the exact MESSAGE statement in code.

1. SAT Runtime Analysis (SAT)

Use SAT to capture the chronological sequence of ABAP execution without interactive debugger access (/h):

Measurement Variant Setup

  1. Open transaction SAT and navigate to Measurement Settings.
  2. Tab: Duration and Type:
    • Aggregation: Set to None (ensures individual calls are recorded chronologically rather than grouped and counted).
    • Measure RFC calls and update calls: Check this box (crucial for IDocs, asynchronous tasks, and EWM update queues).
    • Maximum Size of File: Increase to 50 000 KB or 100 000 KB to prevent premature file truncation.
  3. Tab: Statements:
    • Keep checked: Processing Blocks (Methods, Events, Function Modules, Subroutines) and Database Accesses (Open SQL).
    • Uncheck to reduce noise: Generate and Load (LOAD, GENERATE), Miscellaneous (C calls, Statistics), and Screen (Flow Logic, Modules).
  4. Save the variant (e.g., TRACE_BUG).

Recording & Export

  1. Run the target transaction/report under the variant (or schedule for background user).
  2. On completion, open the measurement in SAT and click the Call Hierarchy tab (F5).
  3. Export the hierarchy:
    • Right-click any row in the ALV tree $\rightarrow$ Spreadsheet... (or Export $\rightarrow$ Local File $\rightarrow$ Text with Tabs).
    • Alternatively, use keyboard shortcut Ctrl + Shift + F7.
  4. Save the text file into the local workspace (e.g. <workspace>/tmp/sat_trace.txt) or share the file path with the agent.

2. ST05 Performance Trace (ST05)

Use ST05 when you need to inspect the runtime parameters sent to the database or external RFCs:

Recording & Export

  1. Open transaction ST05.
  2. Activate trace filtered by User Name or Transaction Code to avoid system-wide trace bloat.
  3. Reproduce the scenario, then deactivate the trace.
  4. Export options:
    • For Performance Bottlenecks: Click Summarized SQL Statements (F8) $\rightarrow$ Export to spreadsheet.
    • For Bug Hunting: Display the Trace List $\rightarrow$ Menu Trace List $\rightarrow$ Save / Export $\rightarrow$ Local File (Text with Tabs).
  5. The agent correlates SQL table keys, WHERE literals, and RETURN_CODE flags with the call structure found in SAT.

3. Application Log Technical Extraction (SLG1)

Application Logs often contain the exact failure explanation, but the default UI translates them into localized human text, hiding the technical message keys.

Method A: Customizing the ALV Layout in SLG1

  1. In the SLG1 message grid, click Change Layout (Ctrl + F8).
  2. Move the following columns from Column Set to Displayed Columns:
    • Message Type (MSGTY)
    • Message Class / ID (MSGID)
    • Message Number (MSGNO)
    • Message Variables 1–4 (MSGV1, MSGV2, MSGV3, MSGV4)
  3. Adopt the layout, then right-click in the grid $\rightarrow$ Spreadsheet... to export.

Method B: Direct Extraction via SE16N (BALHDR + BALM)

  1. In SE16N, open table BALHDR: Filter by OBJECT, SUBOBJECT, date, and user to obtain the 20-digit LOGNUMBER.
  2. In SE16N, open table BALM: Filter by LOGNUMBER to extract raw technical fields (MSGTY, MSGID, MSGNO, MSGV1–MSGV4).
  3. Export the resulting table.

When provided with MSGID and MSGNO, the agent searches the DEV codebase directly for MESSAGE ... <MSGNO>(<MSGID>) to locate the exact decision branch.

Filing Handover & Tooling Incident Reports (sap_file_report)

When agents or developers encounter blocking sap-dev or sap-bridge infrastructure issues (such as ADT LOCK timeouts over Nostr tunnels, unexpected proxy panics, or syntax check hangs), the sap_file_report tool packages the incident into a structured, trackable issue in the configured private GitHub issue tracker. The reporting destination and credentials are maintained with the runtime. The tool returns issue_url and issue_number; viewing the issue requires repository access.

🎯 Scope Boundary: Tooling Defects Only

This issue tracker and reporting tool are strictly reserved for sap-dev / sap-bridge tooling defects, connection failures, and MCP bugs.

  • Allowed: ADT lock/save timeouts, proxy panics, tunnel dropouts, ATC parser quirks, AST engine errors, or MCP tool schema bugs.
  • Prohibited: Resolving customer-specific SAP business logic, custom ABAP algorithm debugging, functional requirements, or general SAP customizing consulting.

🛡️ 3-Tier Privacy & Anonymization Architecture

Private reports receive the same anonymization and human review as any other report:

  1. Tier 1: Agent Anonymization: The agent is instructed to proactively replace developer names, personal user IDs, local Windows file paths (C:\Users\<user>\... $\rightarrow$ C:\Users\[DEVELOPER]), customer company names, project codenames, private RFC1918 IP addresses (10.x.x.x, 192.168.x.x, 172.16-31.x.x), internal hostnames, and live transactional data (such as order numbers or batch IDs).
  2. Tier 2: Mandatory Human Review & Approval: The agent MUST NEVER dispatch reports silently. It drafts the anonymized markdown, presents the full draft and proposed title to the developer in the chat, lists what data was redacted, and waits for explicit user confirmation before submitting.
  3. Tier 3: Daemon Regex Redaction: Before transmitting payloads over HTTPS, sap-bridge runs an automated regex sanitizer across the report text and all attached files (attachment_paths), stripping any remaining Bearer tokens, GitHub PATs (ghp_..., github_pat_...), Nostr private keys (nsec1...), password parameters (password=...), private IPs, and Windows user paths.

📎 File Attachments

The agent can attach relevant diagnostic files (such as SAT call hierarchies, ST05 traces, peeked ABAP source files, or log snippets) by passing their paths in attachment_paths: [...].

  • Attachments are sanitized automatically.
  • Formatted in collapsible <details><summary>📄 filename (size)</summary> ... </details> blocks with syntax highlighting.
  • If the payload fits in GitHub's 65 KB issue body limit, it is embedded directly; otherwise, attachments are cleanly posted as follow-up issue comments.

Clone this wiki locally