diff --git a/README.md b/README.md index eb11a81..d6e4e37 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # railway-chord -Centralized logging for [Railway.app](https://railway.app) projects, powered -by [Vector](https://vector.dev/). +[Vector](https://vector.dev/) log egress for [Railway.app](https://railway.app) +projects. _railway-chord_ pipes the log stream from Railway's GraphQL API into Vector. This gives you **project-wide** centralized logging on Railway. For each Railway @@ -20,7 +20,25 @@ the instructions in the link. The button above will deploy _railway-chord_ on Railway. You will be prompted to set some required environment variables; there is no additional configuration -required beyond this. +required beyond this. Log sinks are automatically configured based on the +presence of required environment variables of each provider, i.e. setting a +`DATADOG_TOKEN` will enable Datadog, and so on. + +### Datadog + +To enable Datadog logs, set the `DATADOG_TOKEN` service variable. + +There is an optional `DATADOG_SITE` setting if your Datadog account is hosted +on a different Datadog instance (defaults to `datadoghq.com`). + +### Logtail + +To enable Logtail, set the `LOGTAIL_TOKEN` service variable. + +### `stdout` + +To enable logging to `stdout`, set `ENABLE_STDOUT=true`. This will output all +enabled project's logs into _railway-chord_'s `stdout`. ### Project IDs @@ -34,6 +52,32 @@ Railway's Dashboard -> Project -> Settings -> General. RAILWAY_PROJECT_IDS="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" ``` +### Log Enrichment + +_railway-chord_ will inject a `railway` object into the logs sent to the provider +containing the deployment/plugin ID and name. + +#### Example: + +```json +{ + "railway": { + "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", + "name": "app.up.railway.app", + "type": "DEPLOYMENT" + } +} +``` + +### Railway API Rate Limit + +Railway's Public API currently has a [rate limit of 1,000 requests daily](https://docs.railway.app/reference/public-api#rate-limits). _railway-chord_ will make ~100 requests every 24 hours for each project enabled. +Work is underway to reduce the amount of requests _railway-chord_ is making (see +[railway-chord#3](https://github.com/half0wl/railway-chord/issues/3)). + +Be careful about this if you're using Railway's API for something else - _railway-chord_ +will eat into your rate limit! + ## Adding Vector sinks ### Request for new sinks @@ -90,11 +134,13 @@ the newly-created config created above, passing the required API key into it: | ----------- | ----------- | | `RAILWAY_API_TOKEN` | **Required**. Railway API token. | | `RAILWAY_PROJECT_IDS` | **Required**. A comma-separated list of Railway Project IDs. | -| `LOGTAIL_TOKEN` | **Required**. Logtail token. | +| `LOGTAIL_TOKEN` | Optional. Logtail token. | +| `DATADOG_TOKEN` | Optional. Datadog API token. | +| `DATADOG_SITE` | Optional. Datadog site setting. Defaults to `datadoghq.com`. | +| `ENABLE_STDOUT` | Optional. Enable Vector logging to stdout. | | `RAILWAY_API_HTTP_ENDPOINT` | Optional. Railway's HTTP GQL Endpoint. Defaults to `https://backboard.railway.app/graphql/v2`. | | `RAILWAY_WS_HTTP_ENDPOINT` | Optional. Railway's WebSockets GQL Endpoint. Defaults to `wss://backboard.railway.app/graphql/v2`. | | `VECTOR_BIN_PATH` | Optional. Path to Vector binary. Defaults to path defined in Docker build. You do not need to set this. | -| `VECTOR_CFG_PATH` | Optional. Path to Vector configuration. Defaults to path defined in Docker build. You do not need to set this. | ## License