update readme

psyb0t · Jul 6, 2024 · a7eaf67 · a7eaf67
1 parent 17b9acd
commit a7eaf67
Showing 1 changed file with 69 additions and 76 deletions.
diff --git a/README.md b/README.md
@@ -1,60 +1,55 @@
-# telegram-logger
+# telegram-logger: Hack Your Logs
 
-[![codecov](https://codecov.io/gh/psyb0t/telegram-logger/branch/master/graph/badge.svg?token=FBYNVHPF8Q)](https://codecov.io/gh/psyb0t/telegram-logger)
-[![goreportcard](https://goreportcard.com/badge/github.com/psyb0t/telegram-logger)](https://goreportcard.com/report/github.com/psyb0t/telegram-logger)
-[![pipeline](https://github.com/psyb0t/telegram-logger/actions/workflows/pipeline.yml/badge.svg)](https://github.com/psyb0t/telegram-logger/actions/workflows/pipeline.yml)
+Welcome to `telegram-logger`, where we turn your logs into Telegram messages. Because logs should be as mobile as you are.
 
-This service is a server that receives log entries via HTTP POST requests and sends them to a Telegram bot. The log entries are expected to be in the form of a JSON object with various fields representing log data and metadata.
+## Table of Contents
 
-## Configuration
+- [What's This?](#whats-this)
+- [Configuration](#configuration)
+- [HTTP API](#http-api)
+- [Telegram Bot](#telegram-bot)
+- [Running the Service](#running-the-service)
+- [Interacting with the Service](#interacting-with-the-service)
+- [Available Clients](#available-clients)
+- [TODO](#todo)
 
-The configuration file is a YAML file that specifies the following fields:
+## What's This?
 
-- ListenAddress: the address that the HTTP server should listen on (e.g. "localhost:8080"). Defaults to "0.0.0.0:80".
-- Logger: a nested object for configuring the logger.
-  - Level: the log level (e.g. "debug", "info", "warning", "error"). Defaults to "debug".
-  - Format: the log format (e.g. "text", "json"). Defaults to "json".
-- TelegramBot: a nested object for configuring the Telegram bot.
-  - Token: the token used to authenticate the connection to the Telegram bot.
-  - SuperuserChatID: the chat ID of the superadmin user.
-- Storage: a nested object for configuring the storage backend.
-  - Type: the type of storage backend to use (e.g. "badgerDB").
-  - BadgerDB: a nested object for configuring the BadgerDB storage backend.
-    - DSN: the Data Source Name (DSN) used to connect to the BadgerDB instance (e.g. "mydatabase").
+`telegram-logger` is a server that receives log entries via HTTP POST requests and sends them to a Telegram chat instance. It's like having a secret agent for your logs.
 
-The configuration file can be specified using the `CONFIGFILE` environment variable or, if not set, the default file `./config.yml` will be used. If the default file does not exist it will try working with the given environment variables (see bellow).
+## Configuration
 
-Here's an example configuration file:
+Your config file is the key to the kingdom. Here's what you can tweak:
 
 ```yaml
 listenAddress: 0.0.0.0:8080
 logger:
   level: debug
   format: json
 telegramBot:
-  token:
+  token: YOUR_SECRET_TOKEN_HERE
   superuserChatID: 38081130
 storage:
   type: badgerDB
   badgerDB:
     dsn: /path/to/db/dir
 ```
 
-All of the settings from the configuration file can also be set via environment variables. The environment variables override any value already present in the config file.
+Prefer environment variables? We've got you covered:
 
-- `LISTENADDRESS`: overrides the listenAddress field in the config struct.
-- `LOGGER_LEVEL`: overrides the level field in the logger struct.
-- `LOGGER_FORMAT`: overrides the format field in the logger struct.
-- `TELEGRAMBOT_TOKEN`: overrides the token field in the telegramBot struct.
-- `TELEGRAMBOT_SUPERUSERCHATID`: overrides the superuserChatID field in the telegramBot struct.
-- `STORAGE_TYPE`: overrides the type field in the storage struct.
-- `STORAGE_BADGERDB_DSN`: overrides the dsn field in the badgerDB struct.
+```bash
+export LISTENADDRESS=0.0.0.0:8080
+export LOGGER_LEVEL=debug
+export LOGGER_FORMAT=json
+export TELEGRAMBOT_TOKEN=YOUR_SECRET_TOKEN_HERE
+export TELEGRAMBOT_SUPERUSERCHATID=38081130
+export STORAGE_TYPE=badgerDB
+export STORAGE_BADGERDB_DSN=/path/to/db/dir
+```
 
 ## HTTP API
 
-The service listens for HTTP POST requests to the root path and sends the request body as a message via the Telegram bot to the user associated with the request (determined by the value of the `X-ID` header). The response body is a JSON object.
-
-### Request
+Send a POST request with your log entry. Don't forget your secret handshake (X-ID header).
 
 ```json
 {
@@ -73,36 +68,26 @@ The service listens for HTTP POST requests to the root path and sends the reques
 }
 ```
 
-### Success response
-
-```json
-{
-  "message": "successfully sent log entry via Telegram"
-}
-```
-
-### Error response
-
-```json
-{
-  "error": "Bad Request: message text is empty"
-}
-```
-
 ## Telegram Bot
 
-The service has a number of commands that can be sent via the Telegram bot by a user. These commands are handled by the app and invoke the corresponding command handler function. The following commands are supported:
+Our bot's got a few commands that you can throw at it:
+
+- `/start`: Get your unique ID
+- `/stop`: Go dark
+- `/getAllUsers`: For the admins
+- `/addUser`: Recruit new agents (admin only) - a user can also be a channel
 
-- /start: generates a unique ID for the user and sends it to the user in a welcome message. The user can then use this ID in the X-ID header of HTTP POST requests to the app to authenticate themselves.
-- /stop: stops sending log entries to the user and removes the user's ID from the database.
-- /getAllUsers (superadmin only): retrieves a list of all users from the database and sends it to the user via the Telegram bot.
-- /addUser (superadmin only): adds a new user to the database by chat ID. (eg. `/addUser 1002080652973`)
+Pro Tip: Adding a channel? Here's how:
 
-## Running the service
+1. Send a message to your target channel
+2. Grab the channel ID from the message URL (e.g., https://t.me/c/2340157712/5)
+3. Add the prefix: `-100`
+4. Use the command: `/addUser -1002340157712`
+5. Grab the ID that the bot sends to the channel(and maybe delete that message) and use it as your `X-ID` header when doing your HTTP request.
 
-When running via using the docker image you will need to use port 80 on the listen address because that's the only one being exposed so you can just not specify it anywhere.
+## Running the Service
 
-### Run via docker
+### Docker
 
 ```bash
 docker run -it \
@@ -119,9 +104,7 @@ docker run -it \
     psyb0t/telegram-logger
 ```
 
-### Run via docker compose
-
-docker-compose.yml
+### Docker Compose
 
 ```yaml
 version: "3.8"
@@ -143,13 +126,15 @@ services:
       - STORAGE_BADGERDB_DSN=/app/db
 ```
 
-```
+Fire it up:
+
+```bash
 docker compose -f docker-compose.yml up
 ```
 
-### Run via latest released binary
+### Binary
 
-`download-latest.sh`
+First, get the latest binary:
 
 ```bash
 #!/usr/bin/env bash
@@ -168,26 +153,26 @@ curl -s -L -o "$asset_name" "$asset_url"
 chmod +x "$asset_name"
 ```
 
-`run.sh`
+Then run it:
 
 ```bash
 export LISTENADDRESS=0.0.0.0:8080
 export LOGGER_LEVEL=debug
 export LOGGER_FORMAT=json
-export TELEGRAMBOT_TOKEN=TOKEN
-export TELEGRAMBOT_SUPERUSERCHATID=CHATID
+export TELEGRAMBOT_TOKEN=YOUR_SECRET_TOKEN_HERE
+export TELEGRAMBOT_SUPERUSERCHATID=YOUR_CHAT_ID_HERE
 export STORAGE_TYPE=badgerDB
 export STORAGE_BADGERDB_DSN=./db
 
 ./telegram-logger-linux-amd64
 ```
 
-## Interacting with the service
+## Interacting with the Service
 
-### curl
+Time to put it to the test:
 
-```
-curl -X POST -H "Content-Type: application/json" -H "X-ID: abcdef" -d '{
+```bash
+curl -X POST -H "Content-Type: application/json" -H "X-ID: YOUR_SECRET_ID" -d '{
   "caller": "myService",
   "time": "2022-03-11T12:34:56.789Z",
   "level": "warning",
@@ -203,11 +188,19 @@ curl -X POST -H "Content-Type: application/json" -H "X-ID: abcdef" -d '{
 }' http://localhost:8080/
 ```
 
-## TODO:
+## Available Clients
+
+- https://github.com/psyb0t/py-telegram-logger-client: For the Pythonistas (module and executable)
+
+More clients in the pipeline. Stay tuned.
+
+## TODO
+
+- More config validation
+- Add healthcheck
+- Add trace id to logs
+- Create external wrapper package based on telegramBotMessageHandler
+- Build embeddable helper packages to interact with a deployed service
+- Fix linting
 
-- more config validation
-- add healthcheck
-- add trace id to logs
-- create external wrapper package based on telegramBotMessageHandler
-- build embeddable helper packages to interact with a deployed service
-- fix linting
+Now go forth and hack those logs! 🖥️