Add a hook that is called whenever an error occurs

[mathijs-ixon]

Describe the feature

When adding a path configuration through the API in which something is wrong, there is currently no automated way to get the error message back (except for parsing the logs).

For example, when username or password for an RTSP source are incorrect MediaMTX logs:
2025/10/20 16:32:20 ERR [path ***] [RTSP source] bad status code: 401 (Unauthorized)

It would be very nice if this error message could be passed through a hook (runOnError?) so it can make its way further into an automated system. The other option would be that error messages would be retrievable through the API somehow, though I feel that would be a more complicated thing to work with.

[debugmenot]

Just as a possible solution that doesn't require the code modification to solve your request:

Adjust logging to file first, then you can monitor the logs with the simple bash script like:

#!/usr/bin/env bash
# log_watcher.sh
# Usage: ./log_watcher.sh /path/to/logfile http://your_hook_endpoint/handler

set -u
LOGFILE="${1:-/var/log/app.log}"
HOOK="${2:-http://your_hook_endpoint/handler}"
# Optional: specify match token (default "ERR")
TOKEN="${3:-ERR}"

# Ensure curl exists
command -v curl >/dev/null 2>&1 || { echo "curl not found"; exit 1; }

echo "Watching '$LOGFILE' for token '$TOKEN' -> POST to $HOOK"

# Handle script exit gracefully
cleanup() {
  echo "Stopping watcher..."
  exit 0
}
trap cleanup SIGINT SIGTERM

# Use tail -F to follow the file (works across rotations)
tail -n 0 -F -- "$LOGFILE" 2>/dev/null |
while IFS= read -r line; do
  # fast check: does the line contain the token?
  if [[ "$line" == *"$TOKEN"* ]]; then
    # Send the whole line as plain text
    # If you want JSON: --data "{\"error\":$(jq -R . <<<"$line")}"
    curl --fail -sS -X POST \
      -H "Content-Type: text/plain; charset=utf-8" \
      --data-binary "$line" \
      "$HOOK" &>/dev/null

    # Optional logging to stdout
    if [[ $? -eq 0 ]]; then
      echo "$(date -Iseconds) SENT: $line"
    else
      echo "$(date -Iseconds) FAILED to send: $line" >&2
    fi
  fi
done