Skip to main content

​
Overview

OmniView uses a settings.json file to configure database connections and client behavior. On first run, if no configuration exists, OmniView will guide you through an interactive setup.

​
Configuration File Location

The configuration is stored in BoltDB (omniview.bolt) in the application directory. The initial configuration can be loaded from a settings.json file.

​
Configuration Structure

​
Basic Example

Here’s a complete example of a settings.json file:
settings.json
{
    "DatabaseSettings": {
        "Database": "FREEPDB1",
        "Host": "127.0.0.1",
        "Port": 1521,
        "Username": "IFSAPP",
        "Password": "ifsapp",
        "Default": true
    },
    "ClientSettings": {
        "EnableUtf8": false
    }
}

​
DatabaseSettings Fields

​
Required Fields

​
Database
string
required
The Oracle database service name or SID. For pluggable databases, use the PDB name (e.g., FREEPDB1).Example: "FREEPDB1", "ORCL", "XEPDB1"
​
Host
string
required
The hostname or IP address of the Oracle database server.Example: "127.0.0.1", "localhost", "db.company.com"
​
Port
integer
required
The TCP port number for Oracle listener. Default Oracle port is 1521.Example: 1521, 1522
​
Username
string
required
The Oracle database user that OmniView will connect as. This user needs specific permissions (see below).Example: "IFSAPP", "SYSTEM", "TRACER_USER"
​
Password
string
required
The password for the database user.
Store settings.json securely. Consider using environment variables or encrypted storage for production deployments.
​
Default
boolean
required
Set to true to mark this as the default connection. Currently, OmniView supports one active connection.Example: true

​
ClientSettings Options

​
EnableUtf8
boolean
default:"false"
Enable UTF-8 character encoding for database communication. Set to true if your database uses UTF-8 and you need proper handling of multi-byte characters.Example: false, true

​
Required Database Permissions

The database user specified in DatabaseSettings.Username needs the following permissions:
1

Execute on DBMS_AQ packages

Required for queue operations:
GRANT EXECUTE ON DBMS_AQ TO your_username;
GRANT EXECUTE ON DBMS_AQADM TO your_username;
2

Create database objects

Required for deploying the tracer package:
GRANT CREATE SEQUENCE TO your_username;
GRANT CREATE TYPE TO your_username;
GRANT CREATE PROCEDURE TO your_username;
3

Session management

Required for subscriber registration:
GRANT CREATE SESSION TO your_username;
OmniView automatically checks for required permissions on startup and will report any missing grants. Run the permission check manually with the deployed Permission_Checks.sql package.

​
Environment Variables

OmniView supports environment variables for sensitive configuration: 
# Oracle Instant Client location (if not in system PATH)
export INSTANT_CLIENT_DIR=/opt/oracle/instantclient_23_7

# Override database password
export OMNIVIEW_DB_PASSWORD=your_secure_password
Environment variables take precedence over values in settings.json. This is useful for CI/CD pipelines or containerized deployments.

​
Multiple Database Configurations

Currently, OmniView supports connecting to one database at a time. The Default: true field indicates which configuration is active.
For managing multiple database configurations:
  1. Create separate settings.json files: 
    settings-dev.json
settings-staging.json
settings-prod.json
  2. Copy the appropriate file before starting OmniView: 
    cp settings-prod.json settings.json
./omniview
  3. Or use different working directories: 
    mkdir -p ~/omniview-dev
cp settings-dev.json ~/omniview-dev/settings.json
cd ~/omniview-dev && ./omniview

​
Configuration Validation

OmniView validates configuration on startup:
1

Connection test

Tests TCP connectivity to Host:Port
2

Authentication

Verifies Username and Password credentials
3

Permission check

Deploys and runs Permission_Checks.sql to verify database grants
4

Package deployment

Deploys OMNI_TRACER_API package if not present
5

Subscriber registration

Registers a unique subscriber for this OmniView instance

​
Common Validation Errors

ErrorCauseSolution
ORA-12541: TNS:no listenerDatabase listener not running or wrong portVerify Host and Port, check listener status with lsnrctl status
ORA-01017: invalid username/passwordWrong credentialsVerify Username and Password
ORA-01031: insufficient privilegesMissing database grantsGrant required permissions (see above)
failed to deploy tracer packageMissing CREATE privilegesGrant CREATE PROCEDURE, CREATE TYPE, CREATE SEQUENCE

​
Advanced Configuration

​
Connection Pooling

OmniView maintains a single persistent connection to the database. Connection pooling is not currently supported but may be added in future versions for multi-tenant scenarios.

​
TNS Names Support

To use TNS names instead of direct connection:
  1. Set environment variable: 
    export TNS_ADMIN=/path/to/tnsnames/directory
  2. Use TNS alias in configuration: 
    {
    "DatabaseSettings": {
        "Database": "MY_TNS_ALIAS",
        "Host": "",
        "Port": 0,
        "Username": "IFSAPP",
        "Password": "ifsapp"
    }
}
When using TNS names, Host and Port can be empty or set to placeholder values as they’re ignored.

​
Next Steps

After configuring OmniView:

Using the Tracer

Learn how to send and view trace messages

Multi-Subscriber Setup

Configure multiple OmniView instances

Build docs developers (and LLMs) love

Get started for freeTalk to us