OpenObserve API Expert

Expert guidance for the OpenObserve API integration - a logging and observability integration for Frappe applications.

Quick Start

Configuration: Single DocType "Open Observe API" with URL, user, password, default organization

Core Functions: send_logs() , search_logs() , test_connection()

Access: System Manager only

Safe Exec: Available as open_observe.send_logs() and open_observe.search_logs()

Core Concepts

OpenObserve: Open-source observability platform for logs, metrics, and traces

Stream: Named channel for organizing logs (e.g., "application-logs", "error-logs")

Organization: Namespace for separating environments (defaults to configured default_org)

Safe Exec Global: Access API from Server Scripts/Business Logic without importing

Timestamps: Use _timestamp or @timestamp fields (Unix microseconds). Frappe datetimes are timezone-naive—use frappe.utils.convert_timezone_to_utc() for accurate timestamps

Common Tasks

Configuration Setup

doc = frappe.get_doc("Open Observe API", "Open Observe API") doc.url = "https://api.openobserve.ai" doc.user = "admin@example.com" doc.password = "secure_password" doc.default_org = "default" doc.save()

Send Logs

From Python:

frappe.call( "tweaks.tweaks.doctype.open_observe_api.open_observe_api.send_logs", stream="application-logs", logs=[{"message": "Event occurred", "level": "info"}] )

From Server Scripts/Business Logic:

open_observe.send_logs( stream="server-logs", logs=[{"message": "Script executed", "user": frappe.session.user}] )

Search Logs

results = open_observe.search_logs( sql="SELECT * FROM application_logs", start_time="2025-12-26T00:00:00Z", end_time="2025-12-26T23:59:59Z", size=100 )

Key Features

Batch Logging: Send multiple logs in single request

Time-based Search: ISO format timestamps auto-converted to Unix microseconds

Query Support: SQL queries and JSON filters for advanced search

Dry Run: Test without actually sending to OpenObserve

Secure Storage: Password encrypted using Frappe's password field

Detailed Documentation

API Functions: See references/api-reference.md for complete parameter documentation

Examples: See references/examples.md for comprehensive usage examples across different contexts and use cases

Troubleshooting: See references/troubleshooting.md for common issues and solutions

Best Practices

• Use descriptive stream names (hierarchical: app-errors , user-activity )

• Include timestamps in all log entries

• Add context (user, doctype, action) to logs

• Batch multiple logs in single request for efficiency

• Handle logging failures gracefully (don't break application)

• Use appropriate log levels (info, warning, error, debug)

• Leverage search for analytics and pattern analysis

Security

• System Manager permission required

• Password stored with Frappe encryption

• HTTP Basic Auth with base64 encoding

• 30-second timeout prevents hanging

• Errors logged to Frappe Error Log