Quick Start Guide

This guide will help you start monitoring Oracle trace messages with OmniView in just a few minutes.

Prerequisites

Before you begin, make sure you have:

✅ Installed OmniView (see Installation)
✅ Oracle Instant Client installed and configured
✅ Access to an Oracle database with required privileges
✅ Created a settings.json configuration file

Setup

Create Configuration File

Create a settings.json file in your working directory:

settings.json

{
    "DatabaseSettings": {
        "Database": "FREEPDB1",
        "Host": "127.0.0.1",
        "Port": 1521,
        "Username": "IFSAPP",
        "Password": "ifsapp",
        "Default": true
    },
    "ClientSettings": {
        "EnableUtf8": false
    }
}

Replace the values with your Oracle database connection details.

Ensure the database user has the following privileges:

CREATE SESSION
CREATE PROCEDURE
CREATE TYPE
EXECUTE on DBMS_AQ and DBMS_AQADM
AQ_ADMINISTRATOR_ROLE or equivalent

Build OmniView

Build the application from source:

make build

This will:

Build the ODPI-C library
Compile the Go application with CGO
Create the omniview binary

Expected output:

[INFO] Checking dependencies...
[OK] All dependencies ready
[BUILD] Building omniview (version: dev)...
   CGO_CFLAGS=...
   CGO_LDFLAGS=...
[OK] Build complete: omniview (dev)

Run OmniView

Start OmniView to begin monitoring:

make run

Or run the binary directly:Unix/macOS:

./omniview

Windows:

.\omniview.exe

On first run, OmniView will:

Auto-update check: On startup, OmniView automatically checks for newer versions from GitHub releases. Development builds (version “dev”) skip this check. To disable updates, build from source without a version flag.

Initialize BoltDB for local state storage
Load database configuration from settings.json
Connect to your Oracle database
Check and deploy the OMNI_TRACER_API package
Initialize the OMNI_TRACER_QUEUE sharded queue
Register your client as a subscriber
Start listening for trace messages

Expected output:

Initializing BoltDB!
✓ Connected to the database
Registered Subscriber: OMNIVIEW_SUB_<unique_id>
dev
[Tracer] Starting event listener for subscriber: OMNIVIEW_SUB_<unique_id>
Tracer started
Press Enter to Continue...

Send Your First Trace Message

Now that OmniView is running and listening, let’s send a trace message from your Oracle database.

Open SQL*Plus or SQL Developer

Connect to your Oracle database as the same user configured in settings.json.

sqlplus IFSAPP/ifsapp@FREEPDB1

Send a Trace Message

Use the OMNI_TRACER_API.Trace_Message procedure to send a message:

BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => 'Hello from OmniView! This is my first trace message.',
        log_level_ => 'INFO'
    );
    COMMIT;
END;
/

Parameters:

message_ (CLOB): The trace message content (can be JSON, text, or any format)
log_level_ (VARCHAR2): Log level - INFO, DEBUG, WARN, ERROR (default: INFO)

You can send JSON payloads for structured logging:

BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => '{"job_id": 12345, "status": "processing", "records": 1500}',
        log_level_ => 'DEBUG'
    );
    COMMIT;
END;
/

View the Message in OmniView

Switch back to your OmniView terminal. You should see the trace message appear immediately:

[2026-03-03 14:25:30] [INFO] SQL*Plus: Hello from OmniView! This is my first trace message.

The output format is:

[TIMESTAMP] [LOG_LEVEL] PROCESS_NAME: PAYLOAD

Success! Your OmniView instance is now monitoring Oracle trace messages in real-time.

How It Works

Behind the Scenes

When you call OMNI_TRACER_API.Trace_Message:

Message Creation: A JSON payload is created with metadata:

{
  "MESSAGE_ID": "unique-guid",
  "PROCESS_NAME": "SQL*Plus",
  "LOG_LEVEL": "INFO",
  "PAYLOAD": "Your message",
  "TIMESTAMP": "2026-03-03T14:25:30Z"
}

Queue Enqueue: The message is enqueued to OMNI_TRACER_QUEUE (a sharded Advanced Queue)
Subscriber Delivery: Oracle AQ delivers the message to all registered subscribers
OmniView Processing:
- The blocking consumer loop (blockingConsumerLoop) waits for messages
- Bulk dequeue operation retrieves messages in batches (see main.go:78)
- Messages are unmarshaled from JSON (see tracer_service.go:89)
- Each message is formatted and displayed (see tracer_service.go:101)

The Message Queue

The OMNI_TRACER_QUEUE is created as a sharded queue for high performance:

Multiple shards: Default 4 shards for parallel processing
Multi-subscriber: Multiple OmniView instances can listen simultaneously
Persistent: Messages are stored until acknowledged
Blocking dequeue: Efficient waiting without polling

Test Different Log Levels

Try sending messages with different log levels:

-- INFO level (default)
BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => 'Application started successfully',
        log_level_ => 'INFO'
    );
    COMMIT;
END;
/

-- DEBUG level
BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => 'Processing batch 1 of 10: 150 records',
        log_level_ => 'DEBUG'
    );
    COMMIT;
END;
/

-- WARN level
BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => 'Performance degradation detected',
        log_level_ => 'WARN'
    );
    COMMIT;
END;
/

-- ERROR level
BEGIN
    OMNI_TRACER_API.Trace_Message(
        message_   => 'Failed to connect to external API',
        log_level_ => 'ERROR'
    );
    COMMIT;
END;
/

Each message will appear in OmniView with its respective log level.

Integration with PL/SQL Code

Integrate trace messages into your existing PL/SQL packages for debugging:

CREATE OR REPLACE PROCEDURE Process_Orders IS
    v_count NUMBER;
BEGIN
    OMNI_TRACER_API.Trace_Message('Starting order processing', 'INFO');
    
    -- Your business logic here
    SELECT COUNT(*) INTO v_count FROM orders WHERE status = 'PENDING';
    
    OMNI_TRACER_API.Trace_Message(
        'Found ' || v_count || ' pending orders',
        'DEBUG'
    );
    
    -- Process orders
    FOR order_rec IN (SELECT * FROM orders WHERE status = 'PENDING') LOOP
        BEGIN
            -- Process order
            Process_Single_Order(order_rec.order_id);
            
            OMNI_TRACER_API.Trace_Message(
                'Processed order: ' || order_rec.order_id,
                'DEBUG'
            );
        EXCEPTION
            WHEN OTHERS THEN
                OMNI_TRACER_API.Trace_Message(
                    'Failed to process order ' || order_rec.order_id || ': ' || SQLERRM,
                    'ERROR'
                );
        END;
    END LOOP;
    
    OMNI_TRACER_API.Trace_Message('Order processing completed', 'INFO');
    COMMIT;
EXCEPTION
    WHEN OTHERS THEN
        OMNI_TRACER_API.Trace_Message(
            'Order processing failed: ' || SQLERRM,
            'ERROR'
        );
        RAISE;
END;
/

Run the procedure and watch the trace messages flow through OmniView in real-time!

Multiple Subscribers

You can run multiple OmniView instances simultaneously. Each will receive all trace messages: Terminal 1:

./omniview

Terminal 2:

./omniview

Both instances will display the same trace messages, enabling team collaboration and distributed monitoring.

Graceful Shutdown

To stop OmniView:

Press Enter in the terminal (as prompted)
Or use Ctrl+C for interrupt signal

OmniView will:

Cancel the context to stop the consumer loop (see main.go:86)
Close database connections gracefully (see main.go:57)
Shut down BoltDB (see main.go:42)
Clean up all resources

Press Enter to Continue...
<Enter>
Event Listener stopping for subscriber: OMNIVIEW_SUB_abc123

Next Steps

API Reference

Learn about the OMNI_TRACER_API procedures and configuration

Architecture

Understand OmniView’s hexagonal architecture and design patterns

Configuration

Explore advanced configuration options and tuning

Development

Build OmniView from source and contribute

Common Issues

No messages appearing in OmniView

Possible causes:

Message not committed: Ensure you run COMMIT; after calling Trace_Message
Different schema: Verify you’re connected as the same user in both OmniView and SQL client
Queue not initialized: Check that “Tracer started” appears in OmniView output

Debug steps:

-- Check if queue exists
SELECT name, queue_type, sharded FROM user_queues WHERE name = 'OMNI_TRACER_QUEUE';

-- Check subscribers
SELECT queue_name, name, address FROM user_queue_subscribers;

Permission denied errors on startup

The database user needs specific privileges. Run this as DBA:

GRANT CREATE SESSION TO your_user;
GRANT CREATE PROCEDURE TO your_user;
GRANT CREATE TYPE TO your_user;
GRANT EXECUTE ON DBMS_AQ TO your_user;
GRANT EXECUTE ON DBMS_AQADM TO your_user;
GRANT AQ_ADMINISTRATOR_ROLE TO your_user;

Connection refused or TNS error

Verify your settings.json configuration:

Host is reachable: ping 127.0.0.1
Port is correct: Default is 1521
Service name is correct: Check with lsnrctl status
Instant Client is in PATH/LD_LIBRARY_PATH

For more configuration options, see the Configuration Guide. Check application logs in BoltDB (omniview.bolt) for detailed debugging.

Getting Started

Core Concepts

Usage Guide

Development

Quick Start

Quick Start Guide

Prerequisites

Setup

Send Your First Trace Message

How It Works

Behind the Scenes

The Message Queue

Test Different Log Levels

Integration with PL/SQL Code

Multiple Subscribers

Graceful Shutdown

Next Steps

API Reference

Architecture

Configuration

Development

Common Issues

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Usage Guide

Development

​Quick Start Guide

​Prerequisites

​Setup

​Send Your First Trace Message

​How It Works

​Behind the Scenes

​The Message Queue

​Test Different Log Levels

​Integration with PL/SQL Code

​Multiple Subscribers

​Graceful Shutdown

​Next Steps

API Reference

Architecture

Configuration

Development

​Common Issues

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Setup

Send Your First Trace Message

How It Works

Behind the Scenes

The Message Queue

Test Different Log Levels

Integration with PL/SQL Code

Multiple Subscribers

Graceful Shutdown

Next Steps

Common Issues