# Error Handling & Monitoring

# 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:

**File:** `atmos.yaml`

```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:**
  ```yaml
  tags:
    team: "platform"
    service: "atmos"
    datacenter: "us-east-1"
  ```

## Enabling Verbose Mode

You can enable verbose mode temporarily via environment variable:

```bash
# 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:

```text
# 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](https://sentry.io)

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

3. **Configure Atmos** with your Sentry DSN:

**File:** `atmos.yaml`

```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:

```bash
# 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:

**File:** `atmos.yaml`

```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:

```yaml
# 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:

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

**File:** `atmos.yaml`

```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](/cli/configuration/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.

**File:** `atmos.yaml`

```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:

```yaml
# 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:

**File:** `atmos.yaml`

```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:

**File:** `atmos.yaml`

```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:

```bash
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:

**File:** `atmos.yaml`

```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
```

```bash
# 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**:
   ```bash
   # Test DSN connectivity
   curl -X POST "${SENTRY_DSN}" -H "Content-Type: application/json" -d '{}'
   ```

2. **Enable debug mode**:

   **File:** `atmos.yaml`
   ```yaml
   errors:
     sentry:
       debug: true
   ```

3. **Verify Sentry is enabled**:
   ```bash
   # 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:
   ```yaml
   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](/cli/configuration/settings/terminal) - Control color output and terminal behavior
- [Common Errors](/troubleshoot/errors) - Solutions to common Atmos errors
- [CLI Configuration](/cli/configuration) - Complete `atmos.yaml` reference

## See Also

- [Sentry Documentation](https://docs.sentry.io/) - Official Sentry docs
- [Configure Validation](/quick-start/advanced/configure-validation) - Stack validation to catch errors early