Diagnostics for support

Collect a diagnostics bundle for SQL Flow support from a pipeline, save raw log bytes on the agent when support asks, and see what each holds and how long it is kept.

When a pipeline stops on something SQL Flow support has to look at, you collect a file from the pipeline's page and send it to them. There are two kinds:

• Download diagnostics is the everyday one: logs, status and configuration with no row data, passwords or keys, downloaded through your browser.
• Save raw log bytes on agent is the exception: the file contains row data from your database, so it is saved on the agent's own disk and never leaves your network unless you send it. Use it only when support asks.

Row data never reaches the control plane. Collecting either file doesn't change the pipeline.

The two kinds at a glance

Download diagnostics

Before you download

• You have the User or Account admin role in the account that owns the pipeline. See Accounts and team.
• The agents that run the pipeline are online and up to date. An agent that is offline or too old is left out, and the file says so. A relay pipeline has two agents, one per half.

Collect the file

1. Open the pipeline and select Actions > Download diagnostics. On a failed pipeline you can instead select Download diagnostics on the Failed, needs operator: banner.
2. Wait while the strip under the banners reads Collecting diagnostics from <agent names>… This takes up to 2 minutes.
3. The browser downloads the file when it is ready, and the strip turns green. Select Download again to save the same file again, or Dismiss to close the strip.

The file is a zip named sqlflow-diagnostics-<pipeline name>-<date>-<time>Z.zip.

What the file contains

The zip holds the pipeline's configuration (without secrets), status, recent commands, log events and alerts from the control plane, and from each agent its release, operating system, free disk space, memory use, status report and recent log lines. Passwords, credentials, access tokens and keys are masked.

The file holds host names, database, user, table and column names and your Configure rules, because support needs them to reproduce a problem. It doesn't hold the contents of rows. Masking works from known message shapes, so read the log excerpts before you attach the file to a public ticket.

If part of the file is missing

If an agent's part is missing, the strip turns amber and reads Diagnostics downloaded without <agent>'s part: <reason>. Send the file to SqlFlow support; it says what is missing. Send the file anyway. If no agent delivers a part in time, the strip turns red and lists each agent's reason.

Save raw log bytes on the agent

SQL Server capture that reads the log through a broker (DirectLog or Reconstruction) stops, without losing any change, when it meets a log block it can't account for. A redacted record of the block goes into Download diagnostics, and the raw block stays on the agent. Most stops are solved from the redacted record. When it isn't enough, the strip says SQL Flow support may ask for the raw log bytes of block <block>: the redacted record alone does not reproduce the stop.

Before you save log bytes

• Support has asked for the raw bytes.
• You are an Account admin of the pipeline's account, signed in as a person. A SuperAdmin who isn't an Account admin of that account can't save the file.
• The agent that holds the bytes is online and up to date.

Save the file

1. Open the pipeline and select Actions > Save raw log bytes on agent (contains row data)….
2. Read the dialog Save raw log bytes on the agent?. It says the file contains row data, stays on the agent for up to 24 hours, isn't uploaded, and that the request is recorded in the audit log under your name.
3. Select Save on agent to consent, or Cancel.
4. Wait while the strip reads Collecting raw log bytes from <agent name>… This takes up to 5 minutes. The browser downloads nothing. The strip turns amber, reads Raw log bytes saved on agent disk, and gives each agent's name, the file's path and when it expires.

If some agents can't save their export, the strip adds Some agents could not save their export. If no agent confirms a saved file, it says No agent-local export receipt is available. Request a new export on an upgraded agent.

Find the file on the agent

The strip gives a path such as support-exports/<32 characters>.zip, relative to the agent's data directory: C:\ProgramData\SqlFlow\Agent by default on Windows and /var/lib/sqlflow-agent on Linux.

• Only the agent's service account can read the folder.
• Each agent keeps at most 8 files (32 MiB). Saving another deletes the oldest.
• A file is removed after 24 hours, or earlier when the agent needs the room.

Copy the file off the agent host when support tells you how, and delete your copy when support confirms they have it.

What reaches the control plane, and how long

The audit log records every request, including refused ones, each agent's part, each diagnostics download with the file's SHA-256, and each expiry.

Send the file to support

1. Collect the file as above. Use Download diagnostics first. Save raw log bytes only if support asks.
2. For diagnostics, email the zip to Spectral Core support at support@spectralcore.com, unless you have agreed a different channel. Include the pipeline's id from the Details card on its Overview tab, the time the problem started, and the steps that reproduce it if you know them.
3. For raw log bytes, ask Spectral Core support for secure transfer instructions. Don't send the file by ordinary email.

If support wants to check a diagnostics file's integrity, its SHA-256 is in MANIFEST.json and in the download's audit entry.

Troubleshooting

See also

• Security considerations
• Audit log
• Accounts and team
• Automatic restart
• Pipeline detail