User Guide¶

The Prodoromos repo contains Sentry config to configure Sentry for your application via Terraform and the Sentry provider. It contains some Terraform modules to make it easier to configure certain common patterns. It also contains a Python CLI to scaffold this Terraform config for new applications.

Development Workflow¶

Install the development dependencies¶

Make sure you have all of the tools specified in the .tool-versions file installed. These are needed to run the pre-commit hooks. You can use a tool version manager like mise-en-place to manage these tools for you automatically.
Run make update to install the pre-commit hooks and development dependencies into your local clone.

Make changes and apply them or iterate¶

Make a GitHub PR after you have made changes to the Terraform config files. This will trigger the following GitHub actions:
- An action that will run all of the pre-commit hooks
- If those all pass, an action that will run a Terraform plan and post it to the PR as a comment
Review the plan and make changes if necessary. Every time you push to the PR, a new Terraform plan will be generated and commented. If you need to manually run a plan, you can comment atlantis plan on the PR.
Get someone to approve the PR.
Comment atlantis apply on the PR. This will apply the changes.
If that goes well (you may be surprised how often it doesn’t), then merge the PR.

Update the docs¶

Parts of the README.md files in the modules in the terraform/modules directory are auto-generated by terraform-docs. The content of those README.md files is then included in the Prodromos documentation. If you change any of the config in those modlues, you need to regenerate those README.md files. This will happen automatically in a pre-commit hook, but if you want to do this yourself, you can build the docs manually with:

make docs

Adding a new application¶

Use the prodromos CLI to create config for a new application:

prodromos new app --name myapp --platform python

This will create a terraform/applications/myapp directory with the following contents.

main.tf¶

This is where the Sentry resources are configured. First, include Terraform modules with information about our Sentry organization and Phalanx environments. See the organization module and environments module docs for more info.

main.tf¶

module "org" {
  source = "../../modules/organization_rubin"
}

module "environments" {
  source = "../../modules/environments"
}

Next, configure some Terraform locals to make the resources easier to specify.

main.tf¶

locals {
  org_slug = module.org.organization.slug
  environments = toset([
    "idfdev",
    "idfint",
    "idfprod",
    "usdfdev",
    "usdfint",
    "usdfprod",
  ])
}

Then, add a Sentry project resource. It uses outputs from the modules we declared earlier. The platform should match the platform of your application.

main.tf¶

resource "sentry_project" "project" {
  organization  = local.org_slug
  teams         = [module.org.teams.square.slug]
  name          = "Noteburst"
  platform      = "python"
  default_rules = false
}

Finally, configure an alert for every environment that our app is in. This example alert will notify that environment’s status Slack channel every frequency_minutes minutes if an event has been captured in that environment during that time period. See the alert_renotify module docs for more details about configuring this alert. This module block makes use of the Terraform for_each meta-argument to create an alert for every environment.

main.tf¶

module "alert_renotify" {
  for_each             = local.environments
  source               = "../../modules/alert_renotify"
  project_slug         = sentry_project.project.slug
  environment_name     = each.value
  organization_slug    = local.org_slug
  slack_status_channel = module.environments[each.value].status_channel
  frequency_minutes    = 15
}

provider.tf¶

This is where Terraform and the Sentry provider are configured. The state is stored in the Google Cloud Storage backend.

provider.tf¶

terraform {

  # Store the Terraform state in a GCS bucket
  backend "gcs" {
    bucket = "some-bucket"
    prefix = "applications/myapp"
  }

  # Pin the Sentry provider
  required_providers {
    sentry = {
      source  = "jianyuan/sentry"
      version = "0.14.3"
    }
  }

  # Restrict the Terraform version
  required_version = ">= 1.11.0"
}

# Looks for a Sentry auth token in the SENTRY_AUTH_TOKEN env var
provider "sentry" {}

The Sentry provider is enabled and configured to get Sentry auth credentials from a SENTRY_AUTH_TOKEN environment variable.

provider.tf¶

# Looks for a Sentry auth token in the SENTRY_AUTH_TOKEN env var
provider "sentry" {}

Configuring Alerts¶

You can use the Sentry provider resources directly to provision alerts for your application, but Prodromos contains terraform modules to make it easier to provision some commonly used alert patterns

alert_renotify module: Send a notification once every frequency_minutes minutes if any events come in to any issues.
alert_new_and_unresolved module: Send a notification only when a new issue is created or if an issue changes from resolved to unresolved.

CLI Reference¶

prodromos¶

Tools for configuring observabilty tooling for Phalanx apps.

prodromos [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

app¶

Tools for configuring applications.

prodromos app [OPTIONS] COMMAND [ARGS]...

new¶

Create a new directory with observability config for your application.

prodromos app new [OPTIONS]

Options

--name <name>¶: Required The name of your application.

--platform <platform>¶

Required Your application’s platform.

Options:: other | android | apple | apple-ios | apple-macos | bun | capacitor | cordova | dart | deno | dotnet | dotnet-aspnet | dotnet-aspnetcore | dotnet-awslambda | dotnet-gcpfunctions | dotnet-maui | dotnet-uwp | dotnet-winforms | dotnet-wpf | dotnet-xamarin | electron | elixir | flutter | go | go-echo | go-fasthttp | go-fiber | go-gin | go-http | go-iris | go-martini | go-negroni | godot | ionic | java | java-log4j2 | java-logback | java-spring | java-spring-boot | javascript | javascript-angular | javascript-astro | javascript-ember | javascript-gatsby | javascript-nextjs | javascript-react | javascript-remix | javascript-solid | javascript-solidstart | javascript-svelte | javascript-sveltekit | javascript-tanstackstart-react | javascript-nuxt | javascript-vue | kotlin | minidump | native | native-qt | nintendo-switch | node | node-awslambda | node-azurefunctions | node-cloudflare-pages | node-cloudflare-workers | node-connect | node-express | node-fastify | node-gcpfunctions | node-hapi | node-koa | node-nestjs | php | php-laravel | php-symfony | powershell | python | python-aiohttp | python-asgi | python-awslambda | python-bottle | python-celery | python-chalice | python-django | python-falcon | python-fastapi | python-flask | python-gcpfunctions | python-pylons | python-pymongo | python-pyramid | python-quart | python-rq | python-sanic | python-serverless | python-starlette | python-tornado | python-tryton | python-wsgi | react-native | ruby | ruby-rack | ruby-rails | rust | unity | unreal

--output-dir <output_dir>¶: Required Directory to output rendered files. Only useful for testing.

-e, --environment <environments>¶: Required Phalanx environments to notify about. Can be specified multiple times.

help¶

Show help for any command.

prodromos help [OPTIONS] [TOPIC] [SUBTOPIC]

Arguments

TOPIC¶: Optional argument

SUBTOPIC¶: Optional argument