Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Add Axiom logging support and update environment configuration (#526)

Bill Yangc8bcd137251a
diff --git a/docker-compose.cloud.yml b/docker-compose.cloud.yml
index 72f4a64c3..a53279a1b 100644
--- a/docker-compose.cloud.yml
+++ b/docker-compose.cloud.yml
@@ -103,6 +103,9 @@ services:
- REDIS_HOST=redis
- REDIS_PORT=6379
- REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
+ # Axiom logging configuration (optional)
+ - AXIOM_DATASET=${AXIOM_DATASET}
+ - AXIOM_TOKEN=${AXIOM_TOKEN}
depends_on:
clickhouse:
condition: service_healthy
diff --git a/server/.env.example b/server/.env.example
index 35a89bb85..729da28d8 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -32,4 +32,8 @@ R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
-R2_PUBLIC_URL=
\ No newline at end of file
+R2_PUBLIC_URL=
+
+# Axiom logging (optional)
+AXIOM_DATASET=
+AXIOM_TOKEN=
\ No newline at end of file
diff --git a/server/AXIOM_SETUP.md b/server/AXIOM_SETUP.md
new file mode 100644
index 000000000..03539179f
--- /dev/null
+++ b/server/AXIOM_SETUP.md
@@ -0,0 +1,121 @@
+# Axiom Logging Setup
+
+This guide explains how to configure Axiom for centralized logging in the Rybbit server.
+
+## Prerequisites
+
+1. Create an Axiom account at https://axiom.co
+2. Create a new dataset for your logs (e.g., "rybbit-logs")
+3. Generate an API token with ingest permissions
+
+## Configuration
+
+Add the following environment variables to your `.env` file:
+
+```env
+# Axiom logging
+AXIOM_DATASET=your-dataset-name
+AXIOM_TOKEN=xaat-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+## How It Works
+
+### Development Mode
+When both `AXIOM_DATASET` and `AXIOM_TOKEN` are set in development:
+- Logs are sent directly to Axiom using the Pino transport
+- This is useful for testing your Axiom integration
+
+Without Axiom credentials in development:
+- Logs use pino-pretty for readable console output
+
+### Production Mode
+In production with Axiom configured:
+- Logs are sent to both Axiom AND stdout simultaneously
+- You can view logs in Axiom for powerful searching and analytics
+- You can still use `docker logs` to see logs locally
+- No additional piping or configuration needed
+
+## Production Setup
+
+For production, you have several options:
+
+### Option 1: Using Axiom's log forwarder
+```bash
+# Install axiom CLI
+curl -fsSL https://install.axiom.co/install.sh | sh
+
+# Run your app and pipe to Axiom
+npm start | axiom ingest $AXIOM_DATASET -t $AXIOM_TOKEN
+```
+
+### Option 2: Docker Compose
+```yaml
+services:
+ app:
+ image: your-app
+ environment:
+ - NODE_ENV=production
+ logging:
+ driver: "json-file"
+
+ log-forwarder:
+ image: axiomhq/axiom-forwarder
+ environment:
+ - AXIOM_DATASET=${AXIOM_DATASET}
+ - AXIOM_TOKEN=${AXIOM_TOKEN}
+ volumes:
+ - /var/lib/docker/containers:/var/lib/docker/containers:ro
+```
+
+### Option 3: Direct in Development
+Set your environment variables and logs will be sent directly to Axiom:
+```bash
+AXIOM_DATASET=your-dataset AXIOM_TOKEN=your-token npm run dev
+```
+
+## Log Structure
+
+All logs include:
+- Service name (e.g., "monitor-scheduler", "notification-service")
+- Structured data as the first parameter
+- Log level (info, warn, error, debug)
+- Timestamp and other metadata
+
+Example:
+```javascript
+logger.info({ monitorId: 123, region: "us-east-1" }, "Health check completed");
+```
+
+## Viewing Logs in Axiom
+
+1. Go to your Axiom dashboard
+2. Select your dataset
+3. Use APL (Axiom Processing Language) to query logs:
+
+```apl
+// View all errors
+| where level == "error"
+
+// View logs from a specific service
+| where service == "notification-service"
+
+// View logs for a specific monitor
+| where monitorId == 123
+```
+
+## Benefits
+
+- Centralized logging across all services
+- Powerful search and analytics
+- Real-time log streaming
+- Alerts and dashboards
+- No log rotation needed
+- Cost-effective for high volume
+
+## Troubleshooting
+
+If logs aren't appearing in Axiom:
+1. Check that environment variables are set correctly
+2. Verify the API token has ingest permissions
+3. Check the dataset name matches exactly
+4. Look for connection errors in stdout logs
\ No newline at end of file
diff --git a/server/package-lock.json b/server/package-lock.json
index 24a7392b1..9746bcc9b 100644
--- a/server/package-lock.json
+++ b/server/package-lock.json
@@ -9,6 +9,7 @@
"version": "1.5.1",
"dependencies": {
"@aws-sdk/client-s3": "^3.842.0",
+ "@axiomhq/pino": "^1.3.1",
"@clickhouse/client": "1.11.1",
"@fastify/cors": "11.0.1",
"@fastify/one-line-logger": "2.0.2",
@@ -942,6 +943,95 @@
"node": ">=18.0.0"
}
},
+ "node_modules/@axiomhq/js": {
+ "version": "1.3.1",
+ "resolved": "https://registry.npmjs.org/@axiomhq/js/-/js-1.3.1.tgz",
+ "integrity": "sha512-Ytf5V3wKz8FKNiqJxnqZmUhjgJ7TItKUoyHVNE/H2V9dN1ozD6NNnsueenOjKdA48cm2sGRyP432nworst18aA==",
+ "license": "MIT",
+ "dependencies": {
+ "fetch-retry": "^6.0.0",
+ "uuid": "^11.0.2"
+ },
+ "engines": {
+ "node": ">=16"
+ }
+ },
+ "node_modules/@axiomhq/js/node_modules/uuid": {
+ "version": "11.1.0",
+ "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
+ "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
+ "funding": [
+ "https://github.com/sponsors/broofa",
+ "https://github.com/sponsors/ctavan"
+ ],
+ "license": "MIT",
+ "bin": {
+ "uuid": "dist/esm/bin/uuid"
+ }
+ },
+ "node_modules/@axiomhq/pino": {
+ "version": "1.3.1",
+ "resolved": "https://registry.npmjs.org/@axiomhq/pino/-/pino-1.3.1.tgz",
+ "integrity": "sha512-zf6p2rU+b5XAk8Nj6EdjqdXTCuWQlf+C8UGdumD9xbtDWBYvk/EYkxXKMqK8mo2Gp+Fi+p5eHgjuOtbeop2XBQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@axiomhq/js": "1.3.1",
+ "pino-abstract-transport": "^1.2.0"
+ },
+ "engines": {
+ "node": ">=16"
+ }
+ },
+ "node_modules/@axiomhq/pino/node_modules/buffer": {
+ "version": "6.0.3",
+ "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz",
+ "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/feross"
+ },
+ {
+ "type": "patreon",
+ "url": "https://www.patreon.com/feross"
+ },
+ {
+ "type": "consulting",
+ "url": "https://feross.org/support"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "base64-js": "^1.3.1",
+ "ieee754": "^1.2.1"
+ }
+ },
+ "node_modules/@axiomhq/pino/node_modules/pino-abstract-transport": {
+ "version": "1.2.0",
+ "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-1.2.0.tgz",
+ "integrity": "sha512-Guhh8EZfPCfH+PMXAb6rKOjGQEoy0xlAIn+irODG5kgfYV+BQ0rGYYWTIel3P5mmyXqkYkPmdIkywsn6QKUR1Q==",
+ "license": "MIT",
+ "dependencies": {
+ "readable-stream": "^4.0.0",
+ "split2": "^4.0.0"
+ }
+ },
+ "node_modules/@axiomhq/pino/node_modules/readable-stream": {
+ "version": "4.7.0",
+ "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-4.7.0.tgz",
+ "integrity": "sha512-oIGGmcpTLwPga8Bn6/Z75SVaH1z5dUut2ibSyAMVhmUggWpmDn2dapB0n7f8nwaSiRtepAsfJyfXIO5DCVAODg==",
+ "license": "MIT",
+ "dependencies": {
+ "abort-controller": "^3.0.0",
+ "buffer": "^6.0.3",
+ "events": "^3.3.0",
+ "process": "^0.11.10",
+ "string_decoder": "^1.3.0"
+ },
+ "engines": {
+ "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+ }
+ },
"node_modules/@better-auth/utils": {
"version": "0.2.5",
"resolved": "https://registry.npmjs.org/@better-auth/utils/-/utils-0.2.5.tgz",
@@ -3955,6 +4045,18 @@
"integrity": "sha512-b5o1I6aLNeYlU/3CPlj/Z91ybk1gUsKT+5NAJI+2W4UjvS5KLG28K9v5UvNoFVjHV8PajVZ00RH3vnjyQO7ZAw==",
"license": "MIT"
},
+ "node_modules/abort-controller": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz",
+ "integrity": "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==",
+ "license": "MIT",
+ "dependencies": {
+ "event-target-shim": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=6.5"
+ }
+ },
"node_modules/abstract-logging": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/abstract-logging/-/abstract-logging-2.0.1.tgz",
@@ -5042,6 +5144,24 @@
"@types/estree": "^1.0.0"
}
},
+ "node_modules/event-target-shim": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/event-target-shim/-/event-target-shim-5.0.1.tgz",
+ "integrity": "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/events": {
+ "version": "3.3.0",
+ "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",
+ "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.8.x"
+ }
+ },
"node_modules/expand-template": {
"version": "2.0.3",
"resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
@@ -5253,6 +5373,12 @@
"walk-up-path": "^4.0.0"
}
},
+ "node_modules/fetch-retry": {
+ "version": "6.0.0",
+ "resolved": "https://registry.npmjs.org/fetch-retry/-/fetch-retry-6.0.0.tgz",
+ "integrity": "sha512-BUFj1aMubgib37I3v4q78fYo63Po7t4HUPTpQ6/QE6yK6cIQrP+W43FYToeTEyg5m2Y7eFUtijUuAv/PDlWuag==",
+ "license": "MIT"
+ },
"node_modules/fflate": {
"version": "0.4.8",
"resolved": "https://registry.npmjs.org/fflate/-/fflate-0.4.8.tgz",
@@ -7003,6 +7129,15 @@
"url": "https://github.com/prettier/prettier?sponsor=1"
}
},
+ "node_modules/process": {
+ "version": "0.11.10",
+ "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz",
+ "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6.0"
+ }
+ },
"node_modules/process-warning": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.0.0.tgz",
diff --git a/server/package.json b/server/package.json
index 8639834bb..816c57e94 100644
--- a/server/package.json
+++ b/server/package.json
@@ -22,6 +22,7 @@
},
"dependencies": {
"@aws-sdk/client-s3": "^3.842.0",
+ "@axiomhq/pino": "^1.3.1",
"@clickhouse/client": "1.11.1",
"@fastify/cors": "11.0.1",
"@fastify/one-line-logger": "2.0.2",
diff --git a/server/src/index.ts b/server/src/index.ts
index 494eb98f5..07f74d3da 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -91,24 +91,47 @@ import { extractSiteId, isSitePublic } from "./utils.js";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
-const isDevelopment = process.env.NODE_ENV === "development";
-const isProduction = process.env.NODE_ENV === "production";
+const hasAxiom = !!(process.env.AXIOM_DATASET && process.env.AXIOM_TOKEN);
const server = Fastify({
logger: {
- level: process.env.LOG_LEVEL || (isDevelopment ? "debug" : "info"),
- transport: isProduction
- ? {
- target: "@fastify/one-line-logger",
- }
- : {
- target: "pino-pretty",
- options: {
- colorize: true,
- translateTime: "SYS:standard",
- ignore: "pid,hostname",
- },
- },
+ level: process.env.LOG_LEVEL || (process.env.NODE_ENV === "development" ? "debug" : "info"),
+ transport:
+ process.env.NODE_ENV === "production" && IS_CLOUD && hasAxiom
+ ? {
+ targets: [
+ // Send to Axiom
+ {
+ target: "@axiomhq/pino",
+ level: process.env.LOG_LEVEL || "info",
+ options: {
+ dataset: process.env.AXIOM_DATASET,
+ token: process.env.AXIOM_TOKEN,
+ },
+ },
+ // Pretty print to stdout for Docker logs
+ {
+ target: "pino-pretty",
+ level: process.env.LOG_LEVEL || "info",
+ options: {
+ colorize: true,
+ translateTime: "SYS:standard",
+ ignore: "pid,hostname",
+ destination: 1, // stdout
+ },
+ },
+ ],
+ }
+ : process.env.NODE_ENV === "development"
+ ? {
+ target: "pino-pretty",
+ options: {
+ colorize: true,
+ translateTime: "SYS:standard",
+ ignore: "pid,hostname",
+ },
+ }
+ : undefined, // Production without Axiom - plain JSON to stdout
serializers: {
req(request) {
return {
@@ -384,6 +407,11 @@ const start = async () => {
await server.listen({ port: 3001, host: "0.0.0.0" });
server.log.info("Server is listening on http://0.0.0.0:3001");
+ // Test Axiom logging
+ if (hasAxiom) {
+ server.log.info({ axiom: true, dataset: process.env.AXIOM_DATASET }, "Axiom logging is configured");
+ }
+
// Initialize uptime monitoring service in the background (non-blocking)
uptimeService
.initialize()
diff --git a/server/src/lib/logger/LOGGING.md b/server/src/lib/logger/LOGGING.md
index 75ae5d8af..98296e104 100644
--- a/server/src/lib/logger/LOGGING.md
+++ b/server/src/lib/logger/LOGGING.md
@@ -130,6 +130,8 @@ Replace console statements with appropriate logger calls:
- `LOG_LEVEL`: Set the minimum log level (trace, debug, info, warn, error, fatal)
- `NODE_ENV`: Determines log format (production vs development)
+- `AXIOM_DATASET`: Axiom dataset name for centralized logging (optional)
+- `AXIOM_TOKEN`: Axiom API token for log ingestion (optional)
## Example Service Refactoring
diff --git a/server/src/lib/logger/logger.ts b/server/src/lib/logger/logger.ts
index c42cb2758..b41a50326 100644
--- a/server/src/lib/logger/logger.ts
+++ b/server/src/lib/logger/logger.ts
@@ -1,23 +1,64 @@
import type { FastifyBaseLogger } from "fastify";
import { pino } from "pino";
+import { IS_CLOUD } from "../const.js";
const isDevelopment = process.env.NODE_ENV === "development";
const isProduction = process.env.NODE_ENV === "production";
+const hasAxiom = !!(process.env.AXIOM_DATASET && process.env.AXIOM_TOKEN);
export const createLogger = (name: string): FastifyBaseLogger => {
- return pino({
- name,
- level: process.env.LOG_LEVEL || (isDevelopment ? "debug" : "info"),
- transport: isProduction
- ? undefined
- : {
- target: "pino-pretty",
- options: {
- colorize: true,
- translateTime: "SYS:standard",
- ignore: "pid,hostname",
+ // Production with Axiom - send to both Axiom and stdout
+ if (isProduction && hasAxiom && IS_CLOUD) {
+ return pino({
+ name,
+ level: process.env.LOG_LEVEL || "info",
+ transport: {
+ targets: [
+ // Send to Axiom
+ {
+ target: "@axiomhq/pino",
+ level: process.env.LOG_LEVEL || "info",
+ options: {
+ dataset: process.env.AXIOM_DATASET,
+ token: process.env.AXIOM_TOKEN,
+ },
},
+ // Pretty print to stdout for Docker logs
+ {
+ target: "pino-pretty",
+ level: process.env.LOG_LEVEL || "info",
+ options: {
+ colorize: true,
+ translateTime: "SYS:standard",
+ ignore: "pid,hostname",
+ destination: 1, // stdout
+ },
+ },
+ ],
+ },
+ }) as FastifyBaseLogger;
+ }
+
+ // Development mode with pretty printing
+ if (isDevelopment) {
+ return pino({
+ name,
+ level: process.env.LOG_LEVEL || "debug",
+ transport: {
+ target: "pino-pretty",
+ options: {
+ colorize: true,
+ translateTime: "SYS:standard",
+ ignore: "pid,hostname",
},
+ },
+ }) as FastifyBaseLogger;
+ }
+
+ // Production without Axiom - plain JSON to stdout
+ return pino({
+ name,
+ level: process.env.LOG_LEVEL || "info",
}) as FastifyBaseLogger;
};
@@ -25,4 +66,4 @@ export const logger = createLogger("rybbit");
export const createServiceLogger = (service: string) => {
return logger.child({ service });
-};
+};
\ No newline at end of file