@0xlucasliao/techops-sidecar

@0xlucasliao/techops-sidecar

Runtime monitoring sidecar for TechOps-managed services. It aligns with SOP-OPS-STACK-001 (health + structured logs + Telegram alerting): polls a health URL, sends a daily UTC midnight heartbeat, tails /logs/<SERVICE_NAME>/app.log, and on [ERROR] lines bundles logs by SESSION_ID and sends a .txt to Telegram.

Install and run

npx --yes @0xlucasliao/techops-sidecar
# or after npm install:
npx techops-sidecar

Required environment variables

Optional TECHOPS_* aliases are supported for the same values (see src/config.js).

Optional environment variables

GitHub Actions → container env

Store secrets per repository (or per environment), then map them in the deploy workflow:

env:
  HEALTH_CHECK_URL: ${{ secrets.HEALTH_CHECK_URL }}
  TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
  TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
  SERVICE_NAME: my-service
  ENVIRONMENT: production
  RUNBOOK_URL: https://wiki.example.com/runbooks/my-service

Docker (multi-stage pattern)

Install the package in the image and run the binary next to your app. Share a read-only volume for logs per SOP (/logs/<service-name>/app.log).

FROM node:22-bookworm-slim AS sidecar
RUN npm install -g @0xlucasliao/techops-sidecar@^1.0.0

FROM your-app-base
COPY --from=sidecar /usr/local/lib/node_modules/@0xlucasliao/techops-sidecar /opt/techops-sidecar
ENV PATH="/opt/techops-sidecar/node_modules/.bin:${PATH}"
# Or: node /opt/techops-sidecar/.../bin/techops-sidecar.js

# Your app writes logs here; sidecar reads read-only.
VOLUME ["/logs/my-service"]

# Example: supervisor or shell starts both processes.

Using npx at runtime (slower cold start, always latest):

RUN npm install -g npm@latest
# CMD runs your app; start sidecar with:
# npx --yes @0xlucasliao/techops-sidecar

Full sample (app + sidecar + GitHub Secrets)

Runnable reference in examples/:

Build locally:

docker build -f examples/Dockerfile.app-with-sidecar -t myapp:with-sidecar .
docker run --rm -p 3000:3000 \
  -e SERVICE_NAME=demo-service \
  -e ENVIRONMENT=local \
  -e TELEGRAM_BOT_TOKEN="your-token" \
  -e TELEGRAM_CHAT_ID="your-chat-id" \
  -e HEALTH_CHECK_URL="http://127.0.0.1:3000/health" \
  myapp:with-sidecar

Secrets rule of thumb: define them in GitHub → Settings → Secrets and variables → Actions, reference them only in workflow env: or docker run -e ..., never as docker build --build-arg for tokens (they can remain in image history).

Log format (mandatory for ERROR bundling)

Lines must match:

[TIMESTAMP] [LEVEL] [SERVICE] [SESSION_ID] MESSAGE

Example:

2026-04-27T14:23:01Z [ERROR] payment-gateway sess-8f2a1c3e Connection to upstream failed: timeout after 30s

Behaviour summary

1. Health — GET HEALTH_CHECK_URL every HEALTH_CHECK_INTERVAL_MS. After HEALTH_CONSECUTIVE_FAILURES consecutive failures, sends one Telegram message (subject to rate limit + dedupe). Counter resets when a request succeeds.
2. Daily heartbeat — Every 00:00:00 UTC, sends an “I’m alive” style message.
3. Logs — Tails the log file from EOF (no backlog replay on restart). On [ERROR], waits LOG_BUNDLE_WINDOW_MS and includes all parsed lines with the same SESSION_ID seen in that window, then sends a UTF-8 .txt document plus caption.

Development

npm test

Licence

MIT