# Patrol

> Patrol is a Go library that buffers events in your service and delivers them in batches to Slack, Discord, Twilio, email, SQL or an HTTP server. Patrol Cloud is the hosted version of that server.

## Key facts

- Go module github.com/kataras/patrol, installed with `go get github.com/kataras/patrol@latest`, requires Go 1.27 or newer
- Licensed BSD-3-Clause, source at https://github.com/kataras/patrol, API reference at https://pkg.go.dev/github.com/kataras/patrol
- Newest version v0.0.8 (not tagged yet; the changelog lists it as unreleased)
- A batch flushes when it reaches MaxBatchSize or BufferInterval elapses, 100 events or 5s by default
- Flushers run concurrently and independently: one failing destination never cancels another, and the joined error names each one
- The HTTP protocol is POST / with a JSON array of events and GET / answering OK, guarded by HTTP Basic or a bearer token, bodies over 32 MiB refused with 413
- Patrol Cloud ingests at https://api.patrol.hellenic.dev from an unmodified patrol.Client
- Built by Hellenic Development (https://hellenic.dev); this site uses no analytics and no tracking cookies

## Destinations

- Slack (`patrol.NewSlack`): One Block Kit message per channel and project, with mentions and file uploads. Required options: Token, Channels.
- Discord (`patrol.NewDiscord`): One message per project group, posted by a bot to the channels you list. Required options: BotToken, Channels.
- Twilio (`patrol.NewTwilio`): SMS, or WhatsApp when both numbers carry the whatsapp: prefix. Required options: AccountSID, AuthToken, FromNumber, ToNumber.
- Email over SMTP (`patrol.NewInbox`): An HTML email per project group, sent over SMTP with STARTTLS when the server offers it. Required options: From, To, Host, Port.
- SQL (`patrol.NewSQL`): Rows in a patrol_events table, 1000 to a statement, in one transaction. Required options: Engine.
- HTTP client (`patrol.NewClient`): Posts the batch as JSON to a patrol Server, or to Patrol Cloud, with a bearer token or a username and password.
- HTTP server (`patrol.NewServer`): An http.Handler that receives those batches and hands them to its own flushers.

Any type with a `FlushEvents(ctx context.Context, evts []*patrol.Event) error` method is a destination too.

## Patrol Cloud plans

- Free ($0): 10,000 events a month, 7 days of history, 2 projects, 2 destinations per project, 4 MiB per batch. One service, one alert channel, no card.
- Pro (Pricing coming soon): 500,000 events a month, 30 days of history, 10 projects, 10 destinations per project, 16 MiB per batch. A production service with a team watching it.
- Business (Pricing coming soon): 5,000,000 events a month, 90 days of history, 50 projects, 25 destinations per project, 32 MiB per batch. Many services, longer history, more people.

The free plan needs no payment method. Pro and Business are not priced yet and the site says so rather than showing a number.

## Pages

- [Home](https://patrol.hellenic.dev/): What Patrol does, how a batch flushes, the 7 destinations, a picture of the console, self-hosting against Patrol Cloud, plans and the FAQ
- [Pricing](https://patrol.hellenic.dev/pricing/): The 3 plans compared limit by limit, with the billing questions
- [Changelog](https://patrol.hellenic.dev/changelog/): Every release, read from the library's own HISTORY file
- [Security](https://patrol.hellenic.dev/security/): How events travel, what is stored, how to report a vulnerability
- [Documentation](https://patrol.hellenic.dev/docs/): Installation and the guides below
- [Console](https://patrol.hellenic.dev/app/): Patrol Cloud, sign in with GitHub
- [Contact](https://patrol.hellenic.dev/contact/): Email and GitHub issues
- [Privacy Policy](https://patrol.hellenic.dev/privacy/)
- [Terms of Service](https://patrol.hellenic.dev/terms/)

## Documentation

### Getting started
- [Overview](https://patrol.hellenic.dev/docs/)
- [Install](https://patrol.hellenic.dev/docs/getting-started/install/)
- [Your first event](https://patrol.hellenic.dev/docs/getting-started/first-event/)

### Producer and events
- [Producer and batching](https://patrol.hellenic.dev/docs/producer/)
- [Events](https://patrol.hellenic.dev/docs/producer/events/)
- [Debug events](https://patrol.hellenic.dev/docs/producer/debug-events/)
- [Shutdown](https://patrol.hellenic.dev/docs/producer/shutdown/)
- [Stacktraces](https://patrol.hellenic.dev/docs/producer/stacktraces/)

### Integrations
- [Slack](https://patrol.hellenic.dev/docs/integrations/slack/)
- [Discord](https://patrol.hellenic.dev/docs/integrations/discord/)
- [Twilio](https://patrol.hellenic.dev/docs/integrations/twilio/)
- [Email](https://patrol.hellenic.dev/docs/integrations/email/)
- [SQL](https://patrol.hellenic.dev/docs/integrations/sql/)
- [HTTP client](https://patrol.hellenic.dev/docs/integrations/http-client/)

### Self-hosting a Server
- [The Server](https://patrol.hellenic.dev/docs/self-hosting/)
- [Deploy](https://patrol.hellenic.dev/docs/self-hosting/deploy/)

### Patrol Cloud
- [Overview](https://patrol.hellenic.dev/docs/cloud/)
- [Projects](https://patrol.hellenic.dev/docs/cloud/projects/)
- [Ingest keys](https://patrol.hellenic.dev/docs/cloud/ingest-keys/)
- [Destinations](https://patrol.hellenic.dev/docs/cloud/destinations/)
- [Rules](https://patrol.hellenic.dev/docs/cloud/rules/)
- [Limits](https://patrol.hellenic.dev/docs/cloud/limits/)

### Custom flushers
- [Write a flusher](https://patrol.hellenic.dev/docs/custom-flushers/)

### Configuration file keys
- [Every option key](https://patrol.hellenic.dev/docs/configuration/)

### Reference
- [Links and examples](https://patrol.hellenic.dev/docs/reference/)
- [Changelog](https://patrol.hellenic.dev/changelog/)

## Common questions

- What is Patrol? Patrol is a Go library that collects the events your service reports and delivers them in batches. You call SendEvent, the producer buffers, and a background loop flushes the batch to every destination you configured: Slack, Discord, SMS, email, a SQL table or another patrol server. Patrol Cloud is the hosted half. The same library posts to api.patrol.hellenic.dev instead, and a console shows the events with their fields and stacktraces. One import, one package, and no agent process to run beside your own.
- Which destinations can Patrol deliver to? Seven: Slack, Discord, Twilio for SMS or WhatsApp, email over SMTP, a SQL database, an HTTP client that posts to a remote patrol server, and that server itself. Each one is a constructor with an options struct carrying json, yaml and toml tags, so it loads straight from a config file. Any type with a FlushEvents(ctx, evts) error method is a destination too, which is how a queue, a webhook or a file gets added without waiting for a release.
- Can I self-host instead of using Patrol Cloud? Yes, and it is the same code either way. Run patrol.NewServer in a service of your own, give it the flushers you want, and point patrol.NewClient at it from everywhere else. Patrol Cloud is that server operated for you, with storage, a console, per-project keys and quotas on top. The wire format does not change: POST / with a JSON array of events, GET / for a connectivity check, Basic auth or one bearer token. Moving between the two is a BaseURL and a credential.
- Is the library free and open source? The library is BSD-3-Clause on GitHub and stays that way. Install it with go get github.com/kataras/patrol@latest and use it in a commercial product with no fee and no key. Patrol Cloud is the paid part, and its free plan covers 10,000 events a month with 7 days of history. Nothing in the library phones home and nothing in it is gated behind an account: a service with a Slack flusher and no Patrol Cloud project keeps working exactly as it did.
- What happens when one destination fails? The others still deliver. Every flusher in a batch runs concurrently and to completion, so a Slack outage does not cancel the SQL write and a wrong SMTP password does not stop the Discord message. The failures are joined into one error, each prefixed with the flusher name, and handed to the OnError callback on ProducerOptions. The library retries nothing and writes nothing to disk: a destination that needs retries wraps itself. On Patrol Cloud the failure is recorded per destination and shown in the console.
- Does Patrol only work with Iris? No. Patrol is a plain Go module with no framework dependency. It behaves the same in a net/http service, a gRPC server, a background worker, a CLI or a test: create one producer at startup, call SendEvent where something happens, call Close on shutdown. The question comes up because the same author wrote the Iris web framework and the two are often used together. Nothing in patrol imports Iris, and nothing in it assumes an HTTP request is in flight.
- Which Go version does Patrol need? Go 1.27 or newer. Version 0.0.6 moved to the standard library uuid and encoding/json/v2 packages and to testing/synctest for its own tests, dropping github.com/google/uuid and golang.org/x/sync on the way. The one remaining dependency is github.com/kataras/basicauth, which the HTTP server uses for constant-time credential checks. Older Go releases are not supported: the module declares 1.27 and the compiler says so before anything runs.
- How do the stacktraces work? patrol.NewException(err) captures the call stack where it is created, then drops the frames nobody reads: the runtime, the testing package, the frames from patrol itself, and any module prefix passed to AddSkipModuleFrames. What is left is outermost first, each frame carrying the function, the module, the file, the line and an in_app flag. Templates render them as vscode://file/path:line links, so a frame in a Slack message or an email opens in your editor on the right line.

## Free plan at a glance

- 10,000 events a month, 7 days of history, 2 projects
- No payment method, no trial clock, the library stays free either way

## Contact

- Email: contact@hellenic.dev
- Issues: https://github.com/kataras/patrol/issues

## Optional

- [Full reference](https://patrol.hellenic.dev/llms-full.txt): Long-form description of the library, the protocol and the hosted service