Logging

Pulumi provides different ways to capture logs for debugging and troubleshooting: automatic logging, which records every operation to an encrypted file you can share securely with the Pulumi team, or can be decrypted locally and program logging for emitting custom diagnostics from your Pulumi programs.

Automatic logging

Starting with Pulumi v3.254.0, the CLI automatically records a log file for every operation and stores it under $PULUMI_HOME/logs.

These log files are encrypted on disk using the stack’s secret manager, if they contain property values, as those can contain secrets. The final file consists of gzip-compressed chunks encrypted with AES256-GCM. By default, logs are rotated out after 7 days, or once the log directory reaches 500 MB, so they won’t fill up your disk. You can change these limits with the PULUMI_LOG_ROTATION_MAX_AGE_DAYS and PULUMI_LOG_ROTATION_MAX_TOTAL_MB environment variables.

Use the following commands to work with automatic logs:

• pulumi logs list lists the available log files.
• pulumi logs decrypt decrypts and displays a log locally. The same stack secret manager used for the original command must be available.
• pulumi logs share re-encrypts a log with a key stored on the Pulumi server side and redacts secrets by default, so it can be shared securely with the Pulumi team — even by posting it on a public GitHub issue. Only Pulumi employees can decrypt a shared log.
• pulumi logs remove removes log files.

CLI verbose logging

Verbose logging of the internals of the Pulumi engine and resource providers can be enabled by passing the -v flag to any pulumi CLI command. Pulumi emits logs at log levels between 1 and 11, with 11 being the most verbose. At log level 10 or below, Pulumi will avoid intentionally exposing any known credentials. At log level 11, Pulumi will intentionally expose some known credentials to aid with debugging, so these log levels should be used only when absolutely needed.

By default, logs are written to the top-level temp directory (usually /tmp or the value of $TMPDIR). The following flags control logging behavior:

• --logtostderr: Write logs to stderr instead of temp files.
• --logflow: Pass the same log level to resource providers. Without this flag, only the Pulumi engine logs at the specified verbosity level, while resource providers use their default log level.

The --logflow flag is particularly useful when debugging cloud provider API interactions. At high verbosity levels (such as -v=9), resource providers will log HTTP requests and responses to their cloud APIs. This helps diagnose issues like incorrect resource references, unexpected 404 errors, or API parameter problems.

$ pulumi up --logtostderr --logflow -v=9 2> out.txt

Enabling logs in a pipeline

If you are running your pulumi up command in a pipeline and are not able to alter the command to add the arguments mentioned above, you can use some of the PULUMI_OPTION_* environment variables instead. The following is the equivalent of the command above:

PULUMI_OPTION_LOGFLOW=true
PULUMI_OPTION_LOGTOSTDERR=true
PULUMI_OPTION_VERBOSE=9

You can find more information on the rest of the PULUMI_OPTION_* environment variables in the CLI environment variables section of our documentation.

Provider Diagnostic Logging

Diagnostic logging can also be controlled with flags and environment variables of the resource providers. For example, Pulumi providers that use a bridged Terraform provider can make use of the TF_LOG environment variable (set to TRACE, DEBUG, INFO, WARN or ERROR) in order to provide additional diagnostic information.

$ TF_LOG=TRACE pulumi up --logtostderr --logflow -v=10 2> out.txt

Program logging

In addition to CLI logging, you can emit custom log messages from within your Pulumi programs using the logging functions provided by the Pulumi SDK. These messages are displayed alongside all other Pulumi output in the CLI and in Pulumi Cloud, and are logged and kept for historical purposes.

pulumi.log.info("message")
pulumi.log.info("message", resource)
pulumi.log.debug("hidden by default")
pulumi.log.warn("warning")
pulumi.log.error("fatal error")

pulumi.info("message")
pulumi.info("message", resource)
pulumi.debug("hidden by default")
pulumi.warn("warning")
pulumi.error("fatal error")

// Optional arguments for logging.
args := &pulumi.LogArgs{
    Resource: resource,
    StreamID: 0,
    Ephemeral: false,
}

ctx.Log.Info("message", nil)
ctx.Log.Info("message", args)
ctx.Log.Debug("hidden by default", nil)
ctx.Log.Warn("warning", nil)
ctx.Log.Error("fatal error", nil)

Pulumi.Log.Info("message");
Pulumi.Log.Info("message", resource);
Pulumi.Log.Debug("hidden by default");
Pulumi.Log.Warn("warning");
Pulumi.Log.Error("fatal error");

public static void stack(Context ctx) {
    ctx.log().info("message");
    ctx.log().info("message", resource);
    ctx.log().debug("hidden by default");
    ctx.log().warn("warning");
    ctx.log().error("fatal error");
}

Combining CLI and program logging

When troubleshooting issues, you may want to use both CLI verbose logging and program logging together:

# Enable both CLI verbose logging and program debug logging
$ pulumi up --logtostderr --logflow -v=9 -d 2> out.txt

This combination provides the most comprehensive view of what’s happening during your Pulumi operations, showing both engine internals and your custom program diagnostics.

Debugging cloud provider API calls

When you encounter errors from cloud providers (such as 404 responses or permission issues), the verbose logs can help you see exactly what API calls are being made. For example:

$ pulumi up --logtostderr --logflow -v=9 2>&1 | grep -i "http"

This is particularly useful for debugging scenarios where:

• A resource property expects a name versus a fully qualified ID
• You’re getting generic errors without clear root causes
• You need to verify the exact API endpoints being called