Tianji Documentation

Tianji is an all-in-one lightweight monitoring application designed to consolidate multiple specialized tools into a single service. It provides three core functionalities:

1. Website Analytics: Tracking metrics like PV (Page Views), UV (Unique Visitors), and page visit counts (similar to GA or Umami).
2. Uptime Monitor: Checking network quality and server connectivity.
3. Server Status: Monitoring server health and status (similar to Prometheus).

It is intended for users who need comprehensive monitoring without the overhead of managing multiple separate services.

The Tianji MCP Server acts as a bridge between AI assistants and the Tianji platform. It exposes survey-related functionality through the Model Context Protocol (MCP), allowing AI assistants to:

• Query survey results
• Get detailed survey information
• Get a list of all surveys in a workspace

AI Router provides a single stable AI endpoint for a group of AI Gateways. It manages request routing, traffic splitting via weights, and automatic fallback to subsequent tiers when retryable failures occur.

Key Use Cases:

• Using one endpoint instead of hard-coding specific AI providers.
• Splitting traffic across multiple gateways using weights.
• Implementing fallback logic (e.g., moving from a primary provider to a backup during outages).
• Gradually migrating traffic between providers by adjusting weights.

Tianji Feed is designed for aggregating and communicating various operational signals. Common use cases include:

• Incident Management: Creating product and infrastructure incident streams across multiple services.
• Deployment Tracking: Managing CI/CD deployment and release notices.
• Business Intelligence: Monitoring billing and subscription signals.
• Operational Alerts: Centralizing security, monitoring, and error alerts.

In Tianji AI Gateway Usage Analytics, user charts (Request Count, Cost, and Token Usage) resolve raw userIds into human-readable labels using the following priority order:

1. The member's non-empty nickname.
2. The member's username.
3. The original userId (fallback if the member cannot be resolved).

Resolved users are displayed in the format: name (userId). If a user is removed or cannot be resolved, the system falls back to the raw userId without additional punctuation to ensure historical data remains readable.

Tianji's unified dashboard consolidates server metrics, endpoint response times, and user experience data into a single view. This allows engineers to correlate disparate data sources without context switching.

Key features include:

• Correlation Capability: View server metrics and user experience data simultaneously to reduce Mean Time to Resolution (MTTR).
• Timeline View: Synchronizes events across different monitoring types (e.g., traffic spikes vs. server resource constraints) to identify cause-and-effect relationships.

The Monitor Redis Broadcast Hardening design ensures that optional Redis Monitor lifecycle synchronization is safe under concurrent events, startup races, Redis disconnects, and database failures.

Key principles:

• PostgreSQL is authoritative: Redis is used for broadcasting, but the final state of any Monitor is always determined by the PostgreSQL database. This prevents delayed or out-of-order Redis messages from overriding the true state in the database.
• Redis is optional: If REDIS_URL is not provided, the system operates without Redis clients and without startup delays.
• Per-Monitor Serialization: Operations for a specific monitorId (updates, state changes, deletions, remote events, and reconciliations) are serialized through an internal queue to prevent race conditions. Different Monitor IDs can still process operations concurrently.

Tianji provides several features to implement cost-aware observability patterns:

• Unified Feed: Correlates checks, metrics, and traces/events in one place. See documentation for Feed state model and Channels.
• Server Status: Lightweight monitoring via the server status reporter.
• Flexible Telemetry: Support for apps and websites via telemetry intro, website tracking script, and events tracking.
• Custom Monitoring: Protect SLOs with minimal overhead using custom script monitors.

Tianji provides a multi-dimensional observability view through three core monitoring capabilities:

Website Analytics

Tracks real-time visitor metrics including:

• Visitor count and geographic distribution
• Page load performance (LCP, FID, CLS)
• User behavior flow tracking
• API response time statistics

Uptime Monitor

Provides continuous availability checking via:

• Second-level heartbeat detection
• Multi-region global probing
• Support for DNS, TCP, and HTTP protocols
• Automatic failover verification

Server Status

Streams infrastructure metrics including:

• CPU, memory, and disk I/O monitoring
• Network traffic and connection status
• Process-level resource consumption
• Container and virtualization metrics