Socorro is the crash pipeline behind Firefox, and it says so plainly

The repository is a pipeline, and the collector lives next door

Socorro is described as a Mozilla-centric crash ingestion pipeline and analysis tools for crash reports using the Breakpad libraries, and the repository description calls it the Mozilla crash ingestion pipeline that accepts and processes Breakpad style crash reports and provides analysis tools.

The first thing to understand is that this repository is not the whole system. The readme splits it in two. Socorro itself covers the processor, the web app and the cron jobs, with the code in this repository, the documentation at socorro.readthedocs.io and bugs filed in Bugzilla under the Socorro product. Antenna is the collector, and it has its own repository and its own documentation, with its own bug component in Bugzilla.

That split is a deliberate architecture. A crash report is a POST from a client that just crashed, so the component that accepts it should be small, isolated and hardened against the traffic of a mass failure, while the component that does the expensive work of symbolication, grouping and analysis can be scaled and restarted independently.

The readme is also direct about the audience. It states that this is a very Mozilla-centric product and that there is currently no capacity to support non-Mozilla uses, and repeats the point in the support section, calling it a Mozilla-specific product without the capacity to support external users.

The licence is MPL-2.0, the homepage is crash-stats.mozilla.org, and the repository is not archived with the last push on 2026-10-20.

Releases are dated tags, and they are frequent

The release model is worth understanding before you decide anything about maintenance.

The readme says the project uses continuous development and releases often, and points at the list of tags for what changes were deployed to production and when. The recent tags follow that pattern: v2026.10.13, v2026.09.16 and v2026.09.03, one or more per month, each named for the day it was cut rather than for a semantic version.

That naming scheme is a Mozilla convention and it carries an implication for anyone planning an upgrade. There is no major, minor and patch ladder to reason about, so there is no stated compatibility promise between a version you run and the next one. A date tag means what went out on that day, and the tag list is the changelog.

The repository root carries WHATSNEW.rst next to the README, which is where the change notes for each release live, alongside a GRAVEYARD.md that documents removed features, a CONTRIBUTING.rst, and a renovate.json for dependency updates. The tooling around the project also shows a team that treats its own dependencies as something to keep current, with .log4brains.yml and a broad set of linters in the configuration.

So the picture on maintenance is a project that ships to production frequently, with the deployment history visible in public. The counterweight is the support statement: frequent releases are for Mozilla.

The stack is Django, Elasticsearch and Google Cloud services

The dependency list in the project metadata is where the architecture becomes concrete.

The Python floor is pinned hard, with requires-python set to 3.11 only, and the web framework is django at 5.2. The storage and analysis side is PostgreSQL through psycopg2 and Elasticsearch at 9.4, with djangorestframework for the API and django-waffle for feature flags, so behaviour can be turned on gradually in production.

The pipeline itself leans on Google Cloud services, with google-cloud-pubsub and google-cloud-storage in the dependency list, and the compose file confirms it by standing up local emulators for both, a pubsub service and a gcs-emulator, alongside postgresql and elasticsearch. Pub/Sub is the queue between the collector and the processor, which is the piece that lets a spike in crash volume be absorbed by a queue rather than by the processing workers.

Two entries in that list are worth pausing on. The sentry-sdk dependency says the crash reports are also forwarded to Sentry, and the compose file includes a fakesentry service so that path can be developed against without a real account. And obs-common is pulled from a private package index named cavendish, hosted at us-python.pkg.dev under the moz-fx-cavendish-prod project, so a piece of shared code is not on the public package index at all.

just recipes wrap the compose file into a developer workflow

Running Socorro locally means running a fairly large set of services, and the repository handles that with a justfile of named recipes on top of Docker Compose.

The recipes are small and explicit. The build recipe builds the images, the setup recipe starts Postgres, Elasticsearch, local Pub/Sub and local GCS and then creates a superuser, and update-data runs the script that adds or updates the necessary database data.

# Set up Postgres, Elasticsearch, local Pub/Sub, and local GCS services.
setup: _env
    docker compose run --rm app shell /app/bin/setup_services.sh
    bin/create_superuser.sh

Every recipe depends on a _env step that copies docker/config/.env.dist to .env if it is not there yet, so a first run does not need hand-written configuration.

The run recipe starts the processor, the web app and the fake Sentry by default, and there is a separate run-submitter recipe that starts the stage submitter and the fake collector, which is how you exercise the ingestion path without a real crashing client. The compose file defines the app, test, devcontainer, processor and crontabber services, each depending on the same set of backing services.

Two small details in the compose file show how much attention the project pays to developer experience. The project name is set to socorro explicitly, because the name would otherwise be derived from the directory name and a clone under a different name breaks the container and network naming. And the build passes userid and groupid from USE_UID and USE_GID, so files written into the mounted volume belong to you rather than to root.

Docker and pytest are the two ways to run things

The test story is a standard Python one, and the dependency list is candid about it: pytest, pytest-django, pytest-env, requests-mock, freezegun and jsonschema are all there, alongside the everett settings library and the dockerflow package that Mozilla uses across its services.

pytest.ini sits at the repository root with the test configuration, and the compose file has a dedicated test service that uses the same application image as production but loads docker/config/test.env instead of the local development environment. The devcontainer service is a third variant, with a different Dockerfile, the repository mounted at /app and the virtual environment directory excluded from the mount so it is not shadowed by the host.

The release and data flow is worth noting too. The version in the project metadata is marked as required but unused, which is a comment that tells you the package version is not what identifies a deployment. The dated tags are.

Everything is orchestrated through uv, with a uv.lock at the root, a tool.uv section that pins the environment to Linux on x86_64 with CPython, and a private index entry for the obs-common package. The lock file plus the pinned interpreter is how a project with a dozen service dependencies keeps a developer's machine and a build agent in step.

The readme points you elsewhere, and the alternatives elsewhere still

Two parts of the readme are about boundaries rather than code, and they are the parts to read first if you are considering adopting this.

The first is the support statement, in two places. The note says the product is very Mozilla-centric and that there is no capacity to support non-Mozilla uses, and the support section says the same thing again with the phrase Mozilla-specific product.

The second is the alternatives list, which the readme frames as a non-exhaustive set of suggestions for anyone who wants to use Socorro for their own product. It separates them into two kinds. Running your own means the electron mini-breakpad-server or the wk8 sentry_breakpad project, both of which are collector-side servers for Breakpad format reports. Hosted or on-premise means Backtrace or BugSplat, which are commercial crash reporting services.

The difference in approach is worth being explicit about. Socorro as Mozilla runs it is a full pipeline, collector plus processor plus web app plus cron jobs plus analysis tooling, backed by Elasticsearch for crash grouping and a Django application for the user interface at crash-stats.mozilla.org. A collector server like mini-breakpad-server is a much smaller thing: it receives reports and stores them, and the processing and analysis live elsewhere.

So if what you need is to accept Breakpad reports from your own clients, a collector is the smaller commitment. If what you need is a complete crash analytics product, the readme is telling you to buy one.

What this repository is actually good for

Knowing that Socorro cannot support you is not the same as it being useless, because it is a large, well documented and openly developed example of a crash processing system.

The documentation lives at socorro.readthedocs.io and covers setting up Socorro, configuration, specifications and development, which is the specification part that matters most for understanding the pipeline: the formats, the stages and the data contract between them.

The code itself is a reference for the parts that are hard to get right. Symbolication and crash grouping are the kind of work that looks simple until you have to do it across many platforms, and the processor in this repository does it for real products, with Elasticsearch doing the grouping work and the analysis tools on top. The fakecollector directory at the root, and the fake Sentry service, show the testing approach: a fake collector that produces synthetic reports so the pipeline can be exercised without breaking anything.

The operational surface is visible too. The cron jobs directory, the datadog and statsd integrations, the djangorestframework API, the feature flag setup, the OIDC integration for authentication, and the fact that a crash pipeline is a service that has to keep working while the client products are crashing is the real design constraint all of it answers.

For a team running its own crash reporting, the honest summary is that Socorro is a fine model to read and a poor dependency to adopt. Take the design, the documentation and the specification, and use one of the alternatives the readme lists for the running.

Editorial conclusion

Socorro fits a team already inside Mozilla's ecosystem, or a reader who wants to understand how a large crash pipeline is put together, since the processor, web app, collector and analysis tooling are all here to read. It is not a product to deploy for your own application, because the project states that it cannot support non-Mozilla uses. Check first that the crash format you need is the Breakpad style the pipeline accepts, that you are prepared to run the whole stack of PostgreSQL, Elasticsearch, Pub/Sub, GCS and Memcached to develop against it, and that the alternatives the readme lists fit your case better than a system designed for one organisation.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. mozilla-services/socorro on GitHub
3. Project website
4. README
5. Releases