Enabling logging

When reporting a Metalama bug, it is often helpful to attach Metalama log files. This document provides instructions on how to generate these logs.

There are possible approaches: produce log files, or write the logging output to the console.

Producing log files

Step 1. Install the Metalama CLI tool

First, install the metalama .NET tool as outlined in Installing the Metalama Command Line Tool.

Step 2. Edit diagnostics.json

Run the following command:

metalama config edit diagnostics

This command will open a diagnostics.json file in your default editor. Make the following changes to this file:

1. In the logging/processes section, set the processes that should have logging enabled to true:
   • Compiler: This refers to the compile-time process.
   • Rider: This is the design-time Roslyn process of the Rider IDE.
   • DevEnv: This is the UI process of Visual Studio. Note that no aspect code runs in this process.
   • RoslynCodeAnalysisService: This is the design-time Roslyn process running under Visual Studio, where the aspect code runs.
2. In the logging/trace section, set the categories that should have logging enabled to true. To enable logging for all categories, set the * category to true.

The following example shows how to enable logging for the compiler process for all categories.

{
    "logging": {
        "processes": {
                "Other": false,
                "Compiler": true,
                "DevEnv": false,
                "RoslynCodeAnalysisService": false,
                "Rider": false,
                "BackstageWorker": false,
                "MetalamaConfig": false,
                "TestHost": false
      },
    "trace": {
        "*": false
      },
    "stopLoggingAfterHours": 5.0
  }
}

To validate the correctness of the JSON file, run the following command:

metalama config validate diagnostics

Step 3. Restart processes

Diagnostic settings are cached in all processes, including background compiler processes and IDE helper processes.

To restart background compiler processes, run the following command:

metalama kill

If you need to alter the logging configuration of the IDE processes, you will need to manually restart your IDE.

Step 4. Execute Metalama

Perform the sequence of actions that you wish to log.

Step 5. Open the log file

You can find the log in the %TEMP%\Metalama\Logs directory.