Table of Contents
OmniView (also known as OmniInspect) is a Message Passing TUI (Text User Interface) application that enables sending event messages and debug traces from Oracle Database. It provides real-time tracing capabilities through Oracle Advanced Queuing (AQ) with a blocking consumer pattern for reliable message delivery.
The application consists of two main components:
- Go Desktop Application - A TUI application that connects to Oracle Database and listens for trace messages
- PL/SQL Package (OMNI_TRACER_API) - Oracle database objects that handle message enqueueing and dequeuing
Download the latest release from the Releases page.
- Open the latest release.
- Download the archive for your platform:
- macOS Apple Silicon:
omniview-darwin-arm64-*.tar.gz - Windows x64:
omniview-windows-amd64-*.zip
- macOS Apple Silicon:
- Extract the archive.
- From the extract directory, run
./omniview(macOS) or.\omniview.exe(Windows PowerShell). The binaries are not installed on PATH.
To build from source instead, see Building from Source.
OmniView supports multiple methods for sending trace messages to Oracle Database:
- Global Trace Procedure - For general-purpose tracing visible to all subscribers
- Subscriber-Specific Procedures - For targeted messages to specific subscribers
- Webhook Integration - For forwarding messages to external systems
The primary general-purpose function for tracing:
OMNI_TRACER_API.Trace_Message(
message_ IN CLOB,
log_level_ IN VARCHAR2 DEFAULT 'INFO'
);This procedure sends a trace message to an Oracle AQ sharded queue. The OmniView application listens for these messages and displays them in real-time.
Parameters:
message_- The trace message content (CLOB)log_level_- Log level (e.g., 'INFO', 'WARN', 'ERROR', 'DEBUG')
Example Usage:
-- Send a simple trace message
BEGIN
OMNI_TRACER_API.Trace_Message('Processing started', 'INFO');
END;
-- Send a JSON payload
BEGIN
OMNI_TRACER_API.Trace_Message(
'{"order_id": 12345, "status": "completed"}',
'INFO'
);
END;OmniInspect supports forwarding trace messages to external HTTP endpoints via webhooks. This enables integration with external monitoring systems, log aggregators, or custom alerting pipelines.
OMNI_TRACER_API.Trace_Message_To_Webhook(
message_ IN CLOB,
log_level_ IN VARCHAR2 DEFAULT 'INFO'
);This procedure sends a trace message with a flag that signals the OmniView application to forward it to the configured webhook URL. The webhook URL must be configured in the OmniView application (prompted on first run).
Parameters:
message_- The trace message content (CLOB)log_level_- Log level (e.g., 'INFO', 'WARN', 'ERROR', 'DEBUG')
Prerequisites:
- A webhook URL must be configured in OmniView (the application prompts for this on first run)
- The receiving endpoint must accept POST requests with JSON payload
Example Usage:
-- Send a trace message to webhook
BEGIN
OMNI_TRACER_API.Trace_Message_To_Webhook('Alert: High latency detected', 'WARN');
END;
-- Send JSON data to webhook
BEGIN
OMNI_TRACER_API.Trace_Message_To_Webhook(
'{"alert": "cpu_high", "value": 95, "threshold": 90}',
'ERROR'
);
END;Important Security Notice: The
Trace_Message_To_Webhookfunction includes basic SSRF (Server-Side Request Forgery) protection that blocks localhost, private IP ranges (RFC1918), link-local addresses, and common cloud metadata endpoints. However, this protection is limited and may not cover all potential security risks. Users are advised to ensure that webhook requests are sent only to secure, trusted endpoints. The maintainers of this open-source project accept no responsibility for any damages or security issues that may arise from the use of this feature. Please exercise caution and validate all webhook URLs before use in production environments.
Category Blocked Localhost localhost,0.0.0.0,::Private IPs 10.x.x.x,172.16-31.x.x,192.168.x.xLink-local 169.254.x.xCloud metadata 169.254.169.254,metadata.google.internalIPv6 equivalents ::1,fe80::/10,fc00::/7Note: VPN ranges, proxy chains, DNS rebinding attacks, and other advanced SSRF vectors are not covered.
OmniInspect supports multi-subscriber tracing with automatically generated, subscriber-specific procedures. When a subscriber is registered in OmniView, the system generates a custom procedure whose name is built from the subscriber's FunnyName() alias and that routes messages specifically to that subscriber.
Procedure Signature:
OMNI_TRACER_API.TRACE_MESSAGE_<FUNNY_NAME>(
message_ IN CLOB,
log_level_ IN VARCHAR2 DEFAULT 'INFO',
process_name_ IN VARCHAR2 DEFAULT NULL
);Parameters:
message_- The trace message content (CLOB)log_level_- Log level (e.g., 'INFO', 'WARN', 'ERROR', 'DEBUG')process_name_- Optional process identifier.
Example Usage:
For a subscriber whose FunnyName() is WEBAPP, OmniView generates the procedure TRACE_MESSAGE_WEBAPP():
-- Send a message to the WEBAPP subscriber
BEGIN
OMNI_TRACER_API.TRACE_MESSAGE_WEBAPP('User login initiated', 'INFO');
END;
-- Send with process name for better organization
BEGIN
OMNI_TRACER_API.TRACE_MESSAGE_WEBAPP(
'Processing payment order #12345',
'INFO',
'payment_service'
);
END;
-- Send an error message
BEGIN
OMNI_TRACER_API.TRACE_MESSAGE_WEBAPP(
'Database connection timeout',
'ERROR'
);
END;Note: The procedure name is based on the subscriber's auto-generated funny name, not the subscriber's display name. OmniView assigns each subscriber a unique funny name (e.g.,
WEBAPP,BARNACLE) at registration time, and the generated procedure always uses that funny name. If you change a subscriber's display name in OmniView, the existing procedure name (and the PL/SQL code calling it) remains unchanged.
Benefits:
- Subscriber-Specific: Messages are routed directly to the target subscriber
- Auto-Generated: Procedures are created automatically when you register a subscriber in OmniView
- Persistent: Procedures persist across application restarts
- Process Tracking: Optional process name parameter helps organize and filter related messages
OmniView follows a hexagonal layout with a small composition root, core domain and ports, service layer, and adapters for Oracle, BoltDB, config, and the Bubble Tea UI. Supporting PL/SQL, CGO, scripts, assets, and reference docs live alongside the Go code, while the detailed source tree is documented in docs/source-tree-analysis.md.
Key areas:
cmd/omniview/- application entry point and wiringinternal/core/- domain models and port interfacesinternal/service/- business logic orchestrationinternal/adapter/- Oracle, storage, config, and UI implementationsassets/andscripts/- embedded SQL, setup, and maintenance helpersdocs/- architecture and deeper project references
Before building OmniView, ensure you have the following installed:
| Requirement | Version | Description |
|---|---|---|
| Go | 1.24+ | Programming language |
| Oracle Instant Client | 23.7+ | Oracle database client libraries |
| GCC/Clang | Any recent version | C compiler for CGO |
| make | Any recent version | Build automation |
- Oracle Instant Client for ARM64
- Download from: Oracle Instant Client macOS ARM64
- Oracle Instant Client for x64
- Download from: Oracle Instant Client Windows x64
- Oracle Instant Client for Linux x64
The easiest way to set up and build the project is using the provided setup script:
# Clone the repository
git clone https://github.com/BasuruK/OmniInspect.git
cd OmniInspect
# Run the setup script with automatic build
python scripts/setup_odpi.py --make
# Run the application
./omniviewIf you prefer to build manually or need more control:
Download and extract Oracle Instant Client to the appropriate directory:
| Platform | Path | Download URL |
|---|---|---|
| macOS ARM64 | /opt/oracle/instantclient_23_7 |
macOS ARM64 Instant Client download |
| Windows x64 | C:\oracle_inst\instantclient_23_7 |
Windows x64 Instant Client download |
| Linux x64 | /opt/oracle/instantclient_23_7 |
Linux x64 Instant Client download |
The ODPI-C library provides Go bindings for Oracle Database. Run the setup script:
# Without building (just setup)
python scripts/setup_odpi.py
# Or with automatic build
python scripts/setup_odpi.py --makeThis script will:
- Download ODPI-C v5.6.4 from GitHub
- Extract header files to
third_party/odpi/include/ - Copy source files to
third_party/odpi/src/ - Build the ODPI-C shared library
Use the Makefile to build:
# Build the application
make build
# Or with a specific version
make build VERSION=v1.0.0
# Build and run
make run./omniviewOn first run, the application will:
- Prompt you to enter your Oracle database connection details (host, port, database name, username, password)
- Create a local BoltDB database file (
omniview.bolt) to store your settings - Deploy the OMNI_TRACER_API package to your Oracle schema
- Initialize the tracer queue
- Register a subscriber
- Start listening for trace messages
OmniView supports multiple database configurations with dynamic switching via the TUI. To switch databases:
- Press
Ctrl+Dto open the Database Settings overlay - Select a different database from the list or add a new one
- The application will dynamically switch to the selected database
| Target | Description |
|---|---|
make build |
Build the Go application |
make build VERSION=x.x.x |
Build with specific version |
make run |
Build and run the application |
make odpi |
Build only ODPI-C library |
make deps |
Check/build dependencies |
make clean |
Remove all build artifacts |
make test |
Run tests |
make install |
Install Go dependencies |
make release VERSION=x.x.x |
Build and package for distribution |
make publish VERSION=x.x.x |
Build, tag and push release (GitHub Actions handles packaging) |
make help |
Show available targets |
Important: Always use
make runormake buildinstead ofgo run cmd/omniview/main.go. The Makefile sets required CGO environment variables (library paths, rpaths) that are needed for the Oracle ODPI-C driver to compile and link correctly.
OmniView uses a Hexagonal (Ports and Adapters) architecture:
┌─────────────────────────────────────────────────────────────────┐
│ Application Bootstrap │
│ (cmd/omniview/main.go) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Services Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tracer │ │ Permission │ │ Subscriber │ │
│ │ Service │ │ Service │ │ Service │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Adapters Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Oracle │ │ BoltDB │ │ Config │ │
│ │ Adapter │ │ Adapter │ │ Loader │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ External Systems │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Oracle │ │ Local │ │
│ │ Database │ │ Storage │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────┐ Trace_Message() ┌─────────────────┐
│ Oracle PL/SQL │ ────────────────────────▶│ OMNI_TRACER │
│ Code │ │ QUEUE │
└─────────────────┘ └────────┬────────┘
│
│ Dequeue
▼
┌─────────────────┐ Display ┌─────────────────┐
│ OmniView TUI │ ◀──────────────────────│ Blocking │
│ (Console) │ │ Consumer │
└─────────────────┘ └─────────────────┘
OmniView uses a screen-based TUI architecture built with Bubble Tea v2 and Lipgloss. The application flows through the following screens:
┌─────────────┐ Animation Complete ┌─────────────┐
│ Welcome │ ─────────────────────────▶│ Loading │
│ (Animated │ │ (Progress │
│ Logo) │ │ Steps) │
└─────────────┘ └───────┬─────┘
│
Config Not Found │
┌───────────────────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ Onboarding │ │ Main │
│ (Database │ │ (Trace │
│ Config) │ │ Console) │
└─────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ Database │
│ Settings │
│ (Overlay) │
└──────┬──────┘
│
▼
┌─────────────┐
│ Add │
│ Database │
│ Form │
│ (Modal) │
└─────────────┘
OmniView ships an in-process MCP server for Cursor, Claude, and other MCP-compatible clients. It is not a separate binary and is not started from this repository. The TUI process owns it. If OmniView is not running, the MCP endpoint is down.
When a user points you at this repository and asks to install or configure the MCP:
- Confirm OmniView is installed. Prefer a release binary. Do not
go runthis repo to stand up MCP. - Start OmniView and wait until the TUI is up. The MCP listener starts with the app, not before.
- Connect over streamable HTTP at
http://127.0.0.1:54332/mcp. Do not use stdio. Do not spawn a second MCP process. - Write the client config below. No bearer token or Authorization header is required. Enable the
omniviewserver in the IDE or coding platform. - Verify with
get_status. Confirm MCP startup succeeded, port 54332 is available, and the client loaded this configuration.
Available tools: get_status, list_databases, add_database, connect_database, set_broadcast_mode, list_traces, clear_traces, get_trace_method.
Prefer user-level configuration.
Cursor: user ~/.cursor/mcp.json (preferred), or project .cursor/mcp.json
Claude Code: the client's user-level or secret storage (preferred), or project .mcp.json
Other MCP hosts: same mcpServers shape.
The MCP listener is local-only (127.0.0.1), has no bearer authentication, and retains Origin and Host validation. Other local processes can access its tools. Existing token files and BoltDB token entries are no longer read or written; old Authorization headers are ignored.
{
"mcpServers": {
"omniview": {
"url": "http://127.0.0.1:54332/mcp"
}
}
}Claude Code also requires
"type": "http". Aurlwithouttypeis treated as stdio and fails to load:
HTTP requests are stateless. Restarting OmniView does not invalidate an MCP session ID, and no credentials need refreshing. A connected client can make tool calls again when the listener returns. If an IDE disables a server after downtime, use its reconnect control; retry policy belongs to that IDE.
The TUI's MCP indicator reports whether the listener is running, not whether an IDE is connected.
The agent gathers id, host, port (typically 1521), service, username, and password in IDE conversation, then passes all fields to add_database with connect: true. No MCP form elicitation is used. Passwords are never included in tool results or application logs; the IDE may retain chat/tool arguments in its own history.
connect: true: save settings, verify Oracle login, deploy/check permissions and the tracer package, then select the database and notify the TUI. Success returnsok,id,saved: true,connected: true, andactive_database.connectomitted orfalse: preserve save-only behavior, including selecting the first configuration if none is selected. Returnssaved: true,connected: false; no Oracle verification occurs.- Missing fields:
invalid_inputwithmissing_fields,saved: false, andconnected: false. The agent asks for those values and submits complete arguments. Invalid ports returnfield_errors. - Connection/check failure after saving: an error result includes the failure code, database
id,saved: true, andconnected: false. Previous database selection is preserved. Retryconnect_databaseusing the returnedid; do not repeatadd_database. - Duplicate IDs remain rejected; no existing settings are overwritten. After a lost response, check
list_databasesbefore retrying a mutation.
One tool call is not an atomic transaction across saving settings and Oracle verification. The verification connection closes after checks; database selection uses the existing TUI notification flow.
- Trace Message View in Client
- Single database sign in
- Domain Driven Design refactor
- Trace Message webhook integration
- New UI with BubbleteaV2/Lipgloss
- Multiple database support with dynamic switching
- Multi-subscriber support with subscriber-specific procedure generation
- Dynamic subscription management and targeted message delivery
- MCP server: shared trace buffer, connector, and 7 tools (status, broadcast, databases, traces)
- Save Trace Messages to file integration
- Connection health/latency/queue/message per second checking
- Light theme support
Contributions are welcome. Please feel free to submit a Pull Request.
Copyright (c) 2026 Basuru Balasuriya. All Rights Reserved.
This software is the exclusive property of Basuru Balasuriya ("the Author"). See the LICENSE file for full terms and conditions.
If you use OmniView in your research or project, please cite it using the following format:
@software{Balasuriya2026OmniView,
author = {Basuru Balasuriya},
title = {OmniView: Oracle Database Message Passing TUI Application},
year = {2026},
url = {https://github.com/BasuruK/OmniInspect},
license = {Proprietary}
}Balasuriya, B. (2026). OmniView: Oracle Database Message Passing TUI Application (Version 0.1.1) [Software]. Retrieved from https://github.com/BasuruK/OmniInspect
Balasuriya, Basuru. 2026. OmniView: Oracle Database Message Passing TUI Application (Version 0.1.1). Software. https://github.com/BasuruK/OmniInspect.
Built with 💖, by Basuru Balasuriya