Skip to main content
emisar

Typesense search

v0.1.20

Read-only diagnostics for a Typesense search node over its HTTP API: health and node/raft state, per-endpoint request stats and system metrics, the collection catalog and individual schemas, API-key metadata, and a tail of slow requests from the server log. One admin API key, streamed over curl stdin, unlocks the stats/metrics/debug endpoints a search-only key cannot read.

8 allowed by default
Pack ID
typesense
Vendor
emisar
OS
linux
Actions
8
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install typesense --hash sha256:3706956c1cd0472f76e15cd44097ffd1cf394ff06f6d972956bb2d27c8be4074

Setup

Every action calls the Typesense HTTP API at $TYPESENSE_URL via curl on the runner host, or tails the server log. The admin API key is read from $TYPESENSE_API_KEY and sent as X-TYPESENSE-API-KEY over curl stdin, so it never appears in the process arguments or the audit log.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • TYPESENSE_URL default http://127.0.0.1:8108

    Base URL of the Typesense node — scheme, host, and port. Each action appends its path (e.g. /collections, /stats.json).

  • TYPESENSE_API_KEY

    Admin API key; sent as X-TYPESENSE-API-KEY over curl stdin, never argv. Most diagnostic endpoints need the admin key — a search-only key cannot read stats/metrics/debug.

  • TYPESENSE_LOG default /var/log/typesense/typesense.log

    Where this host's Typesense server log lives, for slow_requests. Set it when the log is outside /var/log/typesense — slow_requests' own log_path argument is deliberately contained to that directory, so this is how the host administrator, rather than a caller, declares a non-standard location.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read the protected Typesense log across daemon restarts and log rotation.

typesense.slow_requests

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-typesense-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root
sudo test -r /var/log/typesense/typesense.log

Impact: Every Emisar action on this runner executes as root. The Typesense log can contain request paths, timings, and other application data.

Notes

  • Any of TYPESENSE_URL / TYPESENSE_API_KEY you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
  • Every action is a read-only GET. /health needs no key; the rest expect the admin key in TYPESENSE_API_KEY .
  • Mutating operations are deliberately excluded: POST /config, /operations/snapshot, /operations/vote, /operations/db/compact, and /operations/cache/clear are not part of this pack.
  • Logs outside /var/log/typesense : set TYPESENSE_LOG (and allowlist it in the runner's execution.inherit_env ). slow_requests' log_path argument stays contained to /var/log/typesense because a caller supplies it; the environment is host-administrator state. For unrestricted /var/log access, install linux-core, whose name says so.
  • Typesense has no slow-query endpoint — slow requests are written to the server log (enable with --log-slow-requests-time-ms) and read via the slow_requests action.

Verify it works

Runs typesense.health, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify typesense

Install and configure a pack walks through the whole sequence on a host.

Actions 8 total

View on GitHub
  • typesense.collection script low Low — read-only or trivially reversible

    GET /collections/{name}

    Show the schema and document count for a single collection by name. Use when you already know the collection and want just its definition. Requires the admin API key.

    View source on GitHub
  • typesense.collections script low Low — read-only or trivially reversible

    GET /collections

    List all collections on the node with their full schemas and document counts. Use to inventory what is indexed and how big each collection is. Requires the admin API key.

    View source on GitHub
  • typesense.debug script low Low — read-only or trivially reversible

    GET /debug

    Show node version and raft state. The "state" field reports this node's role in the cluster: 1 = LEADER, 4 = FOLLOWER. This is how you read which node is leader vs follower per node. Requires the admin API key.

    View source on GitHub
  • typesense.health script low Low — read-only or trivially reversible

    GET /health

    Check liveness for the Typesense node. Returns {"ok": true} when healthy, and surfaces resource-exhaustion states (out of memory, out of disk) when the node has stopped accepting writes. No API key required.

    View source on GitHub
  • typesense.keys script low Low — read-only or trivially reversible

    GET /keys

    List API key metadata — the key prefix, description, scoped actions, and collections each key may access. The secret value is never returned; only which keys exist and what they are allowed to do. Sensitive: it discloses the set of credentials configured on the node. Requires the admin API key.

    View source on GitHub
  • typesense.metrics script low Low — read-only or trivially reversible

    GET /metrics.json

    Show system and process metrics for the node — CPU utilization, memory usage, and disk usage. Use to see whether the node is resource-constrained. Requires the admin API key.

    View source on GitHub
  • typesense.slow_requests exec medium Medium — changes state, easily reversible

    Recent slow requests from the server log

    Tail slow requests from the Typesense server log — slow requests are written to the server log prefixed "SLOW REQUEST" (enable with --log-slow-requests-time-ms). This greps the log for those lines and tails the most recent ones. Read-only.

    View source on GitHub
  • typesense.stats script low Low — read-only or trivially reversible

    GET /stats.json

    Show per-endpoint request statistics over the last 10 seconds — requests-per-second counters and latency_ms breakdowns per API path. Use to see which endpoints are hot and how slow they are right now. Requires the admin API key.

    View source on GitHub
← Back to registry
Pack reference  Publish your own