Skip to main content

​
Installation Guide

This guide walks you through installing OmniView and configuring the necessary dependencies for your platform.

​
Prerequisites

Before installing OmniView, ensure you have the following:

​
Required Software

OmniView is built with Go 1.24. Download and install from golang.org.Verify your installation:
go version
# Output: go version go1.24 ...
Required for connecting to Oracle databases via ODPI-C.Recommended Version: 23.7 or higherDownload from Oracle Instant Client Downloads
  1. Download Instant Client Basic (64-bit)
  2. Extract to C:\oracle_inst\instantclient_23_7
  3. Add to PATH: C:\oracle_inst\instantclient_23_7
The default path in the Makefile is:
INSTANT_CLIENT_DIR ?= C:/oracle_inst/instantclient_23_7
OmniView uses CGO to interface with ODPI-C. Ensure CGO is enabled:
export CGO_ENABLED=1
Compilers Required:
  • Windows: MinGW-w64 or MSYS2 with GCC
  • macOS: Xcode Command Line Tools
  • Linux: GCC
OmniView uses Make for building. Most Unix systems have it pre-installed.Windows: Install via MSYS2, Git Bash, or WSLVerify installation:
make --version

​
Oracle Database Requirements

  • Oracle Database 12c or higher
  • User with the following privileges:
    • CREATE SESSION
    • CREATE PROCEDURE (for deploying packages)
    • CREATE TYPE (for queue payload types)
    • EXECUTE on DBMS_AQ and DBMS_AQADM
    • AQ_ADMINISTRATOR_ROLE or equivalent AQ privileges
The database user must have permissions to create packages, types, sequences, and manage Advanced Queuing. OmniView will automatically check and report missing permissions on startup.

​
Building from Source

1

Clone the Repository

git clone <repository-url>
cd omniview
2

Install Go Dependencies

Download and tidy Go modules:
make install
This runs:
  • go mod download - Downloads dependencies
  • go mod tidy - Cleans up module files
3

Build ODPI-C Library

Build the Oracle Database Programming Interface for C:
make odpi
This compiles the ODPI-C library from third_party/odpi and creates:
  • Windows: third_party/odpi/lib/odpi.dll (copied to workspace root)
  • macOS: third_party/odpi/lib/libodpi.dylib
The ODPI-C library is built automatically when you run make build, so this step is optional if you’re building the full application.
4

Build OmniView

Build the main application binary:
make build
This compiles the Go application with CGO and creates the omniview binary.Build with version:
make build VERSION=v1.0.0
The version is embedded in the binary via linker flags:
GO_LDFLAGS = -ldflags "-X OmniView/internal/app.Version=$(VERSION)"
5

Verify Installation

Check the binary was created successfully:Unix/macOS:
./omniview --help
Windows:
./omniview.exe --help

​
Installation from Binary Release

Download pre-built binaries from the GitHub Releases page.
  1. Download omniview-windows-amd64-<version>.zip
  2. Extract the archive
  3. The package includes:
    • omniview.exe - Main executable
    • odpi.dll - ODPI-C library
  4. Add the directory to your PATH or run directly
# Run from extraction directory
.\omniview.exe
You still need Oracle Instant Client installed on your system even when using pre-built binaries. The ODPI-C library depends on Oracle Instant Client at runtime.

​
Configuration

Create a settings.json file in your working directory with your Oracle database connection details:
settings.json
{
    "DatabaseSettings": {
        "Database": "FREEPDB1",
        "Host": "127.0.0.1",
        "Port": 1521,
        "Username": "IFSAPP",
        "Password": "ifsapp",
        "Default": true
    },
    "ClientSettings": {
        "EnableUtf8": false
    }
}
​
DatabaseSettings.Database
string
required
Oracle service name or SID (e.g., FREEPDB1)
​
DatabaseSettings.Host
string
required
Database host address
​
DatabaseSettings.Port
number
required
Oracle listener port (typically 1521)
​
DatabaseSettings.Username
string
required
Database username with required privileges
​
DatabaseSettings.Password
string
required
Database password
​
DatabaseSettings.Default
boolean
Mark as default connection configuration
​
ClientSettings.EnableUtf8
boolean
Enable UTF-8 encoding for client connections

​
Troubleshooting

​
CGO Compilation Errors

If you encounter CGO compilation issues, debug with: 
make check-cgo
This shows the CGO compiler flags and verifies the build process.

​
Oracle Instant Client Not Found

If the build fails with “oci.dll not found” or similar:
  1. Verify Instant Client path in Makefile
  2. Set custom path: 
    make build INSTANT_CLIENT_DIR=/custom/path/to/instantclient
  3. Ensure Instant Client is in your PATH (Windows) or LD_LIBRARY_PATH (Linux)

​
Platform-Specific Issues

Install MinGW-w64 or MSYS2:MSYS2 Installation:
  1. Download from msys2.org
  2. Install gcc: pacman -S mingw-w64-x86_64-gcc
  3. Add to PATH: C:\msys64\mingw64\bin
If you get “library not loaded: libodpi.dylib”:
# Set library path
export DYLD_LIBRARY_PATH=$(pwd)/third_party/odpi/lib:$DYLD_LIBRARY_PATH

# Or use install_name_tool to fix paths
install_name_tool -change libodpi.dylib @rpath/libodpi.dylib ./omniview
Oracle client library not found:
# Add Instant Client to library path
export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_7:$LD_LIBRARY_PATH

# Update ldconfig
sudo ldconfig

​
Next Steps

Quick Start

Run your first trace message and start monitoring

Configuration

Learn about advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us