Timeline

The Timeline provides a complete history of all changes to your Terraform states, enabling you to track who changed what and when.

Overview

Every Terraform operation that modifies state is recorded as a transaction:

  • terraform apply operations
  • State imports
  • Resource modifications
  • State migrations

Timeline shows these transactions chronologically with detailed information about each change.

Accessing Timeline

Via UI

  1. Navigate to Insights > Timeline in the sidebar
  2. Browse transactions chronologically
  3. Click a transaction to see details
  4. Use filters to narrow results

Via CLI

First, get your tenant ID:

stategraph user tenants list

Output:

550e8400-e29b-41d4-a716-446655440000    my-org

List transactions for a tenant:

stategraph tx list --tenant 550e8400-e29b-41d4-a716-446655440000

Response:

{
  "results": [
    {
      "id": "455fe705-f27f-4335-9355-dbe8f14098df",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "completed_at": "2024-01-15T10:30:05Z",
      "completed_by": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "state": "committed",
      "tags": {
        "desc": "Backend update"
      }
    }
  ]
}

Get transaction logs:

stategraph tx logs list --tx 455fe705-f27f-4335-9355-dbe8f14098df

Response:

{
  "results": [
    {
      "id": "log-123",
      "action": "state_set",
      "object_type": "instance",
      "created_at": "2024-01-15T10:30:00Z",
      "state_id": "state-123",
      "data": { ... }
    }
  ]
}

Transaction Properties

Property Description
id Unique transaction ID
created_at When the transaction started
created_by User or system that initiated
completed_at When the transaction finished
completed_by User or system that completed
state Transaction state (open, committed, aborted)
tags Metadata tags (pipeline info, commit, etc.)

Transaction States

State Description
open Transaction in progress
committed Successfully finished
aborted Cancelled or failed

Filtering Timeline

By Time Period

Filter transactions by date range:

  • Last hour
  • Last 24 hours
  • Last 7 days
  • Last 30 days
  • Custom range

By User

Filter to see changes by specific users:

Created by: user@example.com

By State

Filter to transactions affecting specific states:

State: networking/production

By Tags

Filter by transaction tags:

Tag: pipeline=github-actions

Transaction Details

Clicking a transaction shows:

Summary

  • Transaction ID
  • Start and end times
  • Duration
  • User information
  • Tags

Logs

Detailed log of changes:

Field Description
action Type of change (state_set, lock, unlock)
object_type What was changed (instance, state)
state_id Affected state
data Change details

Affected Resources

List of resources modified in this transaction:

  • Resources added
  • Resources modified
  • Resources removed

Use Cases

Audit Trail

Track who made changes for compliance:

  1. Filter by time period
  2. Export transaction list
  3. Review user activity
  4. Document changes

Debugging

Understand unexpected state changes:

  1. Identify when a change occurred
  2. See what was changed
  3. Find who made the change
  4. Review the context (tags, pipeline)

Rollback Planning

Before reverting changes:

  1. Find the transaction that caused issues
  2. Review what was changed
  3. Plan the rollback
  4. Execute and verify

Transaction Tags

Tags provide context about transactions:

CI/CD Integration

When running Terraform from CI/CD, add tags:

# In your Terraform backend config
# Tags are passed via the API during state operations

Common tags:

Tag Example Purpose
pipeline github-actions CI/CD system
commit abc123 Git commit
branch main Git branch
run_id 12345 CI run ID
triggered_by push Trigger type

Creating Transactions with Tags

Via CLI:

stategraph tx create \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=github-actions \
  --tag commit=abc123 \
  --tag branch=main

Best Practices

1. Use Meaningful Tags

Add context to transactions:

{
  "tags": {
    "pipeline": "terraform-ci",
    "commit": "abc123",
    "ticket": "INFRA-456",
    "environment": "production"
  }
}

2. Regular Review

  • Check Timeline weekly for unexpected changes
  • Monitor for unauthorized modifications
  • Verify CI/CD transactions complete successfully

3. Export for Compliance

Periodically export transaction data:

  • Monthly audit reports
  • Compliance documentation
  • Change management records

4. Correlate with Incidents

When issues occur:

  1. Note the time of the incident
  2. Check Timeline for recent changes
  3. Identify potentially related transactions
  4. Review change details

Monitoring

Open Transactions

Monitor for stuck transactions:

stategraph tx list --tenant 550e8400-e29b-41d4-a716-446655440000 | \
  jq '.results[] | select(.state == "active")'

Abort Stuck Transactions

If a transaction is stuck:

stategraph tx abort --tx 455fe705-f27f-4335-9355-dbe8f14098df

Next Steps