# PVS\-Studio analyzer diagnostic logging


> Currently, this feature is available only for the \`pvs\-studio\-analyzer\` and \`PVS\-Studio\_Cmd\` utilities\\\.

Diagnostic logging is designed for quick collection of reproducible information about the analyzer run: actual parameters, environment, execution result, and details about which files were analyzed or skipped\.

The result is saved as a structured log \(JSON\), which is convenient for reading, automated processing, and submitting to technical support\.

If you encounter problems with the analyzer \(crashes, abnormal termination, and other scenarios that prevent normal use of PVS\-Studio\), attach the obtained logs when contacting technical support\. You can contact technical support via [the form](https://pvs-studio.com/en/about-feedback/) on the website\.

## Terms \(used further in the text\)

**Structured log** is a text file containing diagnostic information in JSON format\. Suitable for machine processing\.

**Raw log** is a text file with intermediate information from which the structured log is formed\. Has the suffix `*-raw.PVS-Studio.log`\. The file is not intended for self\-troubleshooting\.

**Analyzer \(frontend\)** — `pvs-studio-analyzer` \(`CompileCommandsAnalyzer`\) and `PVS-Studio_Cmd`;

**Executor** \(of the analysis; is started by the analyzer\) — `pvs-studio`\.

## When to use

It is recommended to enable diagnostic logging if:

* the analysis finished with an error \(non\-zero return code\) or crashed;
* analysis settings were "not applied" or applied differently than expected;
* expected files were not included in the analysis;
* a user needs to confirm configuration details \(for audit/certification/incident investigation\);
* detailed information is required to contact support\.

## Quick start

1\) Run analysis with generation of a structured log:

```cpp
# For pvs-studio-analyzer (CompileCommandsAnalyzer):
pvs-studio-analyzer analyze <your_usual_analysis_flags> \
  --enable-logging ./pvs-diag.json

# For PVS-Studio_Cmd:
PVS-Studio_Cmd <your_usual_analysis_flags> \
  --enableLogging ./pvs-diag.json
```

After execution, the following will appear:

* structured log: `./pvs-diag.json`;
* analyzer raw log \(in case of a crash\): `./*-raw.PVS-Studio.log`\.

If the structured log was not generated \(due to any error\), start the conversion manually:

```cpp
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json
```

### How it works

1. Run the analyzer with logging enabled\.
1. During operation, diagnostic data is written to raw logs\.
1. When the analysis is completed, a structured JSON log is generated\.
1. If something goes wrong during JSON generation, raw logs remain on disk\. They can be [converted manually using the `pvs-diag-collector` utility](https://pvs-studio.com/en/docs/manual/7185/#how_to_manual) or sent to support\.

## Enabling logging and its options

`--enable-logging <file_path>` is a mandatory flag that enables logging and saves the structured JSON log to the specified file\.

**Logging options**

Options are set using the `--logging-options <option1,option2,...>` flag\. Values are passed separated by commas, without spaces\. 

Correct version:

```cpp
--logging-options skip-sensitive,dump-intermediate-files
```

Incorrect version:

```cpp
--logging-options skip-sensitive, dump-intermediate-files
```

Available options:

|No\\\.|Option|Description|
|---|---|---|
|1|\`skip\-sensitive\`|Minimizes and partially masks sensitive data in logs\\\. For example, environment variable values and some artifacts—depending on the analysis scenario\\\.|
|2|\`dump\-intermediate\-files\`|Saves intermediate files after analysis—for example, preprocessed \`\.i\` and configuration \`\.cfg\` files, as well as raw logs\\\.|
|3|\`embed\-runs\`|Adds extended information about executed runs to the structured log, if available in the collected data\\\.|



Examples:

```cpp
# For pvs-studio-analyzer (CompileCommandsAnalyzer):
pvs-studio-analyzer analyze <your_usual_flags> \
  --enable-logging ./pvs-diag.json \
  --logging-options skip-sensitive,dump-intermediate-files,embed-runs

# For PVS-Studio_Cmd:
PVS-Studio_Cmd <your_usual_flags> \
  --enable-logging ./pvs-diag.json \
  --logging-options skip-sensitive,dump-intermediate-files,embed-runs
```

### Manual raw log conversion \(pvs\-diag\-collector convert\)

`pvs-diag-collector` is a utility for collecting/processing logs and related artifacts of PVS\-Studio analyzer operation\.

The `convert` command of the `pvs-diag-collector` utility converts the analyzer raw log \(`*-raw.PVS-Studio.log`\) into a structured one\.


> In a normal workflow, these actions are performed by the analyzer automatically\\\.

**Usage**

```cpp
pvs-diag-collector.exe convert [FILE] [-i <FILE>] [-o <FILE>]
                               [--embed-runs] [-j <NUM>]
```

**Utility options**

|No\\\.|Option|Description|
|---|---|---|
|1|\`\-i\`, \`\-\-input\`|Path to the input raw log\\\.|
|2|\`\-o\`, \`\-\-output\`|Path to the output structured log\\\. If the option is not specified, the result is output to \`stdout\`\\\.|
|3|\`\-\-embed\-runs\`|Adds extended information about executed runs to the structured log, if available in the collected data\\\.|
|4| \`\-j\`, \`\-\-threads\`|Number of threads \\\(by default the number is 1\\\)\\\. When used without an argument or with the \`0\` value, it sets the number of threads automatically\\\.|

**Examples**

```cpp
# Output to a file with detailed information about executor operations
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json              \
                           -–embed-runs
# Output to a file
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json
# Output to console
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log
```

**Return codes**

* `0` is success;
* `1` is an error \(error text also outputs\)\.

## How to read a structured log

The main fields and hints for typical problems are described below\. A complete description of all fields is in the JSON schema \(see [the section about viewing in the editor](https://pvs-studio.com/en/docs/manual/7185/#json_log_ease_of_use)\)\.

### Main sections

It is usually useful to start with the following fields:

* `basicPerformance` indicates time and memory;
* `configuration` — actual analyzer settings;
* `environment` indicates OS/platform/environment variables;
* `input` indicates actual launch arguments, used settings and configurations;
* `output` is a return code, `stdout`/`stderr`, indicators of problems;
* `runs` indicates, which files were analyzed/failed/skipped;
* `utility` indicates, which utility generated the log, its version, and path\.

### Anomalies

During the conversion of raw analyzer logs, "anomalies" may be detected—these are hints about potential problems—output in `stderr`, unsuccessful statuses, version mismatches, etc\.

They can be found in `output.anomalies`\.


> An anomaly is not always an error, but almost always a useful signal for checking and contacting technical support\\\.

### Typical use cases

This section indicates typical logging use cases and log fields to pay attention to\.

**Analysis finished with an error / crashed:**

* `output.returnCode`;
* `output.stderr and output.stdout`;
* `output.anomalies` \(if present\)\.

**File was not included in the analysis \(skipped\):**

* `runs.skipped[]`\.
* `runs.skipped[].sourceFilePath`\.
* `runs.skipped[].skipReason`\.
* path/exclusion settings in `input`\.

**Need to confirm the actual launch configuration:**

* `input.arguments`;
* configuration files/settings in `configuration`;
* \(if available\) `runs.executed[].stages.analysis.details` sections of the final configuration in executor logs\.

**Performance issue;**

* `basicPerformance.elapsedTime`;
* `basicPerformance.peakMemoryConsumption`\.

### Viewing the log in an editor with field hints

The structured log contains a `$schema` field\. If the editor can get the JSON schema, it will:

* show field descriptions on hover;
* suggest valid values;
* highlight type and structure errors\.

**Recommended scenario**

1. Open the JSON log in a code editor \(for example, Microsoft Visual Studio Code\)\.
1. Ensure the value of `$schema` is accessible in the corporate network/internet—according to your policy\. If the file at the specified link is unavailable, change the link to the same file in the analyzer distribution\.
1. Use the editor hints to navigate fields and check the structure correctness\.
1. If access to `$schema` is restricted by corporate policy, it usually helps to publish the schemas on an internal artifact server \(intranet\) or install the schemas locally with mapping in VS Code settings \(`json.schemas` parameter\)\. You can also change the link to the same file in the analyzer distribution\.

### JSON schemas for structured logs of utilities from the PVS\-Studio distribution

Links to these files are written into the `$schema` field of each structured log\. If for some reason you cannot access them locally, use the links below:

* [pvs\-studio\-analyzer V1](https://files.pvs-studio.com/media/logging-system/schemas/log_pvs-studio-analyzer_v1.schema.json);
* [pvs\-studio\-analyzer V2](https://files.pvs-studio.com/media/logging-system/log_pvs-studio-analyzer_v2.schema.json);
* [pvs\-studio\-cmd V1](https://files.pvs-studio.com/media/logging-system/log_pvs-studio-cmd_v1.schema.json);
* [pvs\-studio V1](https://files.pvs-studio.com/media/logging-system/schemas/log_pvs-studio_v1.schema.json);
* [pvs\-studio V2](https://files.pvs-studio.com/media/logging-system/log_pvs-studio_v2.schema.json);
* [pvs\-studio\-dotnet V1](https://files.pvs-studio.com/media/logging-system/log_pvs-studio-dotnet_v1.schema.json)\.

## Privacy and security requirements

Diagnostic logs may contain confidential information:

* paths to source code and build artifacts;
* compilation/preprocessing parameters;
* environment variables;
* parts of output from third\-party tools\.

If passing such information is critical, use `--logging-options skip-sensitive`, which minimizes and partially masks sensitive data in logs\. Also follow these steps:

* before sending logs, perform an internal check—search for tokens/secrets/URLs/project names;
* if necessary, coordinate the transfer channel with the organization security policy\.

## What to send to technical support

Recommended set:

* structured log \(`*.json`\), specified in `--enable-logging`;
* additionally, for C/C\+\+ analyzer:
  * preprocessed files \(`*.PVS-Studio.i`\) related to the problematic file \(will appear after specifying the `--dump-intermediate-files` option\);
  * run configuration files \(`*.PVS-Studio.cfg`\) related to the problematic file \(will appear after specifying the `--dump-intermediate-files` option\);
  * stacktrace files \(`*.PVS-Studio.stacktrace.txt`\);
  * any additional files to clarify the problem \(header files, source code files\)\.

## FAQ

### Where are the logs located?

**Analyzer structured log**

Saved exactly at the path a user specified in `--enable-logging`\.

**Executor structured log**

Not created separately; embedded into the analyzer structured log when the `embed-runs` option is specified\.

**Analyzer raw log**

Saved in the same directory as the file from `--enable-logging`, but with the suffix `*-raw.PVS-Studio.log`\.

**Executor raw log**

Executor raw logs are saved next to the analyzed source files\. Their common feature is that the filename ends with `*-raw.PVS-Studio.log`\.

**How to find all raw logs in a project**

Linux/macOS \(bash\):

```cpp
find <project_folder> -name '*-raw.PVS-Studio.log'
```

Windows PowerShell:

```cpp
Get-ChildItem -Path <project_folder> -Recurse -Filter "*-raw.PVS-Studio.log"
```

### Can I view the contents of log files?

Yes, all files are text files\. You can open any of them and view the contents\.

### I don't see the structured JSON log\. What should I do?

Find the analyzer raw log next to the `--enable-logging` path\.

Run the conversion manually:

```cpp
pvs-diag-collector convert --input <path_to_raw_log> --output ./pvs-diag.json
```

If the conversion fails, send the raw log to support\.

### Why do raw logs remain after analysis?

By default, temporary files and raw logs are deleted when the analysis is completed\. Raw logs are saved \(not deleted\) if at least one of the following conditions is met:

* the `--logging-options dump-intermediate-files` option is enabled;
* the analyzer terminated abnormally\.

Practical outcome: even in case of a crash, a user still has raw logs that can be converted or [sent to support](https://pvs-studio.com/en/about-feedback/) in their original form\.

### Can the log be used in automation \(CI/scripts\)?

Yes\. The structured log is a valid JSON, suitable for parsing\.

If you need to integrate conversion into a pipeline, use `pvs-diag-collector convert` and check the return code \(0/1\)\.

### How to study the log most conveniently?

Open the JSON in VS Code: `$schema`allows you to see hints for fields and valid values\. This speeds up navigation and reduces the risk of errors in interpretation\.