Error Handling & Monitoring

Configure how Atmos formats and reports errors, including Sentry integration for monitoring command failures across your organization.

Why Monitor Atmos Errors?

When running Atmos across an organization—especially in CI/CD pipelines—staying on top of failures can be a significant challenge. Atmos provides built-in error monitoring capabilities to help you:

• Track infrastructure deployment failures across multiple teams and environments
• Identify patterns in configuration errors before they affect production
• Debug CI/CD pipeline issues with detailed stack traces and context
• Monitor the health of your infrastructure automation at scale
• Receive alerts when critical Atmos operations fail

Configuration

The errors section in atmos.yaml controls error formatting and Sentry integration:

atmos.yaml

errors:
  format:
    verbose: false

  sentry:
    enabled: true
    dsn: "https://examplePublicKey@o0.ingest.sentry.io/0"
    environment: "production"
    release: "1.0.0"
    sample_rate: 1.0
    debug: false
    capture_stack_context: true
    tags:
      team: "platform"
      service: "atmos"
      datacenter: "us-east-1"

Configuration Reference

Error Formatting

format.verbose

Show detailed stack traces and context in error messages.

Environment variable: ATMOS_VERBOSE Default: false

When false (compact mode):

• Clean, user-friendly error messages
• Actionable hints and suggestions
• Essential context only

When true (verbose mode):

• Full stack traces with file/line information
• Complete error chain showing how the error propagated
• Detailed context tables with all metadata

Sentry Integration

sentry.enabled

Enable or disable Sentry error reporting.

Default: false

sentry.dsn

Sentry DSN (Data Source Name) from your Sentry project settings. This is the endpoint where errors are sent.

Example: https://examplePublicKey@o0.ingest.sentry.io/0

sentry.environment

Environment name for error grouping in Sentry (e.g., "production", "staging", "ci").

Example: production

sentry.release

Release version for tracking errors by deployment. Useful for identifying regressions.

Example: 1.0.0 or commit-abc123

sentry.sample_rate

Percentage of errors to send to Sentry. Use values between 0.0 and 1.0.

Default: 1.0 (100% of errors sent) Example: 0.5 sends 50% of errors

sentry.debug

Enable debug mode for troubleshooting the Sentry integration. Outputs additional diagnostic information.

Default: false

sentry.capture_stack_context

Include surrounding code context in stack traces sent to Sentry.

Default: true

sentry.tags

Custom key-value tags for filtering and grouping errors in Sentry. These appear as searchable attributes in the Sentry UI.

Example:

tags:
  team: "platform"
  service: "atmos"
  datacenter: "us-east-1"

Enabling Verbose Mode

You can enable verbose mode temporarily via environment variable:

# Enable verbose errors for a single command
ATMOS_VERBOSE=true atmos terraform plan

# Or set it globally in your shell
export ATMOS_VERBOSE=true

Error Message Structure

Atmos formats errors as structured markdown with the following sections:

1. Error - Clear description of what went wrong
2. Explanation - Detailed context about why it failed
3. Example - Code snippets showing the correct approach
4. Hints - Actionable suggestions to fix the problem
5. Context - Key-value pairs (component, stack, region, etc.)
6. Stack Trace - Full error chain (verbose mode only)

Example error output:

# Error

component 'vpc' not found in stack 'prod/us-east-1'

## Hints

💡 Use 'atmos list components --stack prod/us-east-1' to see available components
💡 Check if the component is defined in your stack manifests
💡 Verify the stack name is correct: prod/us-east-1

## Context

| Key       | Value           |
|-----------|-----------------|
| component | vpc             |
| stack     | prod/us-east-1  |

Sentry Integration

What Gets Sent to Sentry?

Atmos only sends command failures to Sentry—errors that prevent a command from completing successfully and cause Atmos to exit with a non-zero exit code.

Errors sent to Sentry:

• ✅ Command failures (invalid arguments, missing configuration)
• ✅ Component not found errors that block deployments
• ✅ Stack validation errors preventing infrastructure changes
• ✅ Workflow execution failures
• ✅ Authentication/authorization errors
• ✅ File system errors (missing atmos.yaml, unreadable stack files)

Errors NOT sent to Sentry:

• ❌ Debug/trace log messages
• ❌ Warnings (e.g., deprecated configuration options)
• ❌ Non-fatal errors that Atmos recovers from
• ❌ Successful commands (exit code 0)

Information included with each error:

1. Error message and type - What went wrong
2. Hints → Sentry breadcrumbs to help debug the issue
3. Context → Tags like component name, stack name, region (PII-safe)
4. Exit code → Command exit code for automation
5. Stack traces → Full error chain with file/line information for debugging
6. Environment → From errors.sentry.environment config
7. Custom tags → From errors.sentry.tags config

This ensures Sentry focuses on actionable failures that affect users, without overwhelming it with internal logging or successful operations.

Setting Up Sentry

1. Create a Sentry project at sentry.io

2. Get your DSN from Project Settings → Client Keys (DSN)

3. Configure Atmos with your Sentry DSN:

atmos.yaml

errors:
  sentry:
    enabled: true
    dsn: "https://your-public-key@o0.ingest.sentry.io/your-project-id"
    environment: "production"
    tags:
      team: "platform"

4. Test the integration by triggering an error:

# This will fail and send an error to Sentry
atmos terraform plan invalid-component -s nonexistent-stack

5. Verify in Sentry that the error appears in your project's Issues dashboard

Environment-Specific Configuration

Configure different Sentry settings per environment:

atmos.yaml

errors:
  sentry:
    enabled: true
    dsn: "https://your-public-key@o0.ingest.sentry.io/project-id"

    # Use environment variable for dynamic environment name
    # Set ATMOS_ENVIRONMENT in your CI/CD pipeline
    environment: !env ATMOS_ENVIRONMENT

    # Set release from CI/CD pipeline
    # Example: "v1.2.3" or "commit-abc123"
    release: !env CI_COMMIT_TAG

    # Reduce noise in development
    sample_rate: 0.1  # Only 10% of errors in dev

Then in your CI/CD pipeline:

# GitHub Actions example
- name: Deploy infrastructure
  env:
    ATMOS_ENVIRONMENT: production
    CI_COMMIT_TAG: ${{ github.ref_name }}
  run: |
    atmos terraform apply vpc -s prod/us-east-1

Privacy & Security

PII-Safe Context:

Atmos uses structured context (via .WithContext()) that is designed to be PII-safe:

• ✅ Component names, stack names, regions
• ✅ File paths (relative, not absolute)
• ✅ Exit codes
• ✅ Error types

What is NOT sent:

• ❌ Environment variable values (unless explicitly added)
• ❌ Secrets or credentials
• ❌ User input data
• ❌ File contents

Sensitive DSN Handling:

Store your Sentry DSN securely:

# Don't commit DSN to version control
# Use environment variables instead
export ATMOS_SENTRY_DSN="https://your-public-key@sentry.io/project-id"

atmos.yaml

errors:
  sentry:
    enabled: true
    dsn: !env ATMOS_SENTRY_DSN
    environment: "production"

Use Cases

Using Profiles for CI vs. Local Development (Recommended)

The recommended approach is to use Atmos profiles to separate CI/CD error monitoring from local development. This keeps your base configuration clean and avoids the need for environment variables on every command.

atmos.yaml

# Base configuration - Sentry disabled by default for local development
errors:
  format:
    verbose: true  # Helpful for local debugging
  sentry:
    enabled: false

# CI profile - enables Sentry for pipeline monitoring
profiles:
  ci:
    errors:
      format:
        verbose: false  # Cleaner CI logs
      sentry:
        enabled: true
        dsn: !env SENTRY_DSN
        environment: !env CI_ENVIRONMENT
        release: !env CI_COMMIT_SHA
        tags:
          pipeline: !env CI_PIPELINE_ID
          branch: !env CI_COMMIT_BRANCH
          team: "platform"

Then in your CI/CD pipeline, activate the profile:

# GitHub Actions example
- name: Deploy infrastructure
  env:
    SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
    CI_ENVIRONMENT: production
    CI_COMMIT_SHA: ${{ github.sha }}
    CI_PIPELINE_ID: ${{ github.run_id }}
    CI_COMMIT_BRANCH: ${{ github.ref_name }}
  run: |
    atmos terraform apply vpc -s prod/us-east-1 --profile ci

This approach provides:

• Local development: Verbose errors, no Sentry noise, fast iteration
• CI/CD pipelines: Clean logs, full Sentry monitoring, actionable alerts
• No environment variables needed locally: Just run atmos terraform plan without any setup

Monitoring CI/CD Pipelines

Track infrastructure deployment failures across all your CI pipelines:

atmos.yaml

errors:
  sentry:
    enabled: true
    dsn: !env SENTRY_DSN
    environment: "ci"
    tags:
      pipeline: !env CI_PIPELINE_ID
      branch: !env CI_COMMIT_BRANCH
      team: "platform"

This allows you to:

• Filter errors by pipeline, branch, or team in Sentry
• Track error rates over time
• Set up alerts for critical failures
• Identify patterns (e.g., "VPC component fails in prod but not staging")

Multi-Team Organizations

Different teams can share the same Sentry project with custom tags:

atmos.yaml

errors:
  sentry:
    enabled: true
    dsn: !env SENTRY_DSN
    environment: !env ENVIRONMENT
    tags:
      team: !env TEAM_NAME        # "platform", "security", "data"
      service: "atmos"
      region: !env AWS_REGION

Then set team-specific environment variables:

export TEAM_NAME="platform"
atmos terraform apply vpc -s prod/us-east-1

Development vs. Production (Environment Variables)

If you prefer environment variables over profiles, you can reduce noise in development while maintaining full monitoring in production:

atmos.yaml

errors:
  format:
    verbose: !env DEVELOPMENT false

  sentry:
    enabled: !env SENTRY_ENABLED false
    dsn: !env SENTRY_DSN
    environment: !env ENVIRONMENT development
    sample_rate: !env SENTRY_SAMPLE_RATE 0.1

# Development (local machine)
export DEVELOPMENT=true
export SENTRY_ENABLED=false

# Production (CI/CD)
export SENTRY_ENABLED=true
export SENTRY_SAMPLE_RATE=1.0
export ENVIRONMENT=production

Troubleshooting

Errors Not Appearing in Sentry

1. Check DSN is correct:

   # Test DSN connectivity
   curl -X POST "${SENTRY_DSN}" -H "Content-Type: application/json" -d '{}'

2. Enable debug mode:

   atmos.yaml

   errors:
     sentry:
       debug: true

3. Verify Sentry is enabled:

   # Check if SENTRY_ENABLED is set
   echo $SENTRY_ENABLED
   
   # Trigger a test error
   atmos terraform plan nonexistent -s invalid

4. Check sample rate: If sample_rate < 1.0, some errors may be dropped

Too Many Errors in Sentry

1. Adjust sample rate for noisy environments:

   errors:
     sentry:
       sample_rate: 0.1  # Only 10% of errors

2. Filter by environment: Use environment tags to separate CI from production

3. Use Sentry's ignore rules: Configure in Sentry UI to filter out known issues

Related Documentation

• Terminal Configuration - Control color output and terminal behavior
• Common Errors - Solutions to common Atmos errors
• CLI Configuration - Complete atmos.yaml reference

See Also

• Sentry Documentation - Official Sentry docs
• Configure Validation - Stack validation to catch errors early