oracledbreceiver

README

Oracle DB Receiver

This receiver periodically queries an Oracle Database host to collect metrics.

Status
Stability	development: logs
	alpha: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@dmitryax, @crobert-1, @atoulme

Getting Started

To use the Oracle DB receiver you must define how to connect to your DB. This can be done in two ways, defined in the Primary and Secondary configuration option sections. Defining one of the two configurations is required. If both are defined, the primary option will be used.

Primary Configuration Option

Required options:

• datasource: Oracle database connection string. Special characters must be encoded. Refer to Oracle Go Driver go_ora documentation for full connection string options.

Example:

receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"

Secondary Configuration Option

Required options:

• endpoint: Endpoint used to connect to the Oracle DB server. Must be in the format of host:port
• password: Password for the Oracle DB connection. Special characters are allowed.
• service: Oracle DB service that the receiver should connect to.
• username: Username for the Oracle DB connection.

Example:

receivers:
  oracledb:
    endpoint: localhost:51521
    password: p@sswo%d
    service: XE
    username: otel

Optional Configuration Options

• collection_interval (default = 10s): The interval at which metrics should be emitted by this receiver.
• initial_delay (default = 1s): The initial time period this receiver waits before starting.
• timeout (default = 0): Timeout for each Oracle DB request. Disabled by default.

Permissions

Instance detection

These grants are required to populate the oracle.db.version, oracle.db.role, oracle.db.open_mode, and oracle.db.pdb resource attributes. Detection is best-effort; failures are logged at warn level and the receiver continues.

GRANT SELECT ON V_$INSTANCE TO <username>;
GRANT SELECT ON V_$DATABASE TO <username>;

Note: sys_context('USERENV', ...) queries against DUAL require no additional grant and are available to all database users.

Hosting type detection (Oracle >=19c only)

These grants are required to populate the oracle.db.hosting_type resource attribute. Only applies to Oracle 19c and later. Detection is best-effort; failures are logged at warn level and the receiver continues.

GRANT SELECT ON V_$DATAFILE TO <username>;
GRANT SELECT ON V_$PDBS TO <username>;        -- OCI detection, connected to PDB only
GRANT SELECT ON CDB_SERVICES TO <username>;   -- OCI confirmation, connected to PDB only

Metrics collection

Depending on which metrics you collect, you will need to assign these permissions to the database user:

GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$SYSSTAT TO <username>;
GRANT SELECT ON V_$RESOURCE_LIMIT TO <username>;
GRANT SELECT ON DBA_TABLESPACES TO <username>;
GRANT SELECT ON DBA_DATA_FILES TO <username>;
GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS TO <username>;

Events collection

These grants are required for the db.server.query_sample, db.server.top_query, and db.server.session.wait_sample events.

GRANT SELECT ON V_$SQL TO <username>;
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL TO <username>;
GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$SESSION_EVENT TO <username>;
GRANT SELECT ON V_$LOCK TO <username>;
GRANT SELECT ON V_$CONTAINERS TO <username>;
GRANT SELECT ON DBA_OBJECTS TO <username>;
GRANT SELECT ON DBA_PROCEDURES TO <username>;

[!NOTE] In the SQL query plan details, the LAST_*, OUTPUT_ROWS, and STARTS columns are populated only when Oracle is configured to collect execution plan statistics (for example, STATISTICS_LEVEL=ALL or the GATHER_PLAN_STATISTICS hint). Otherwise, these fields will be NULL or empty. Configuring this Oracle instrumentation may introduce additional runtime overhead. Enable it only if you need these runtime execution statistics for query performance analysis.

ALTER SYSTEM SET statistics_level = ALL;

Enabling metrics.

See documentation.

You can enable or disable selective metrics.

Example:

receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
    metrics:
      oracledb.query.cpu_time:
        enabled: false
      oracledb.query.physical_read_requests:
        enabled: true

Enabling events.

The following is a generic configuration that can be used for the default logs and metrics scraped by the Oracle DB receiver.

receivers:
  oracledb:
    collection_interval: 10s                     # interval for overall collection
    datasource: "oracle://otel:password@localhost:51521/XE"
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
      db.server.session.wait_sample:
        enabled: true
    top_query_collection:                        # this collection exports the most expensive queries as logs
      max_query_sample_count: 1000               # maximum number of samples collected from db to filter the top N
      top_query_count: 200                       # The maximum number of queries (N) for which the metrics would be reported
      collection_interval: 60s                   # collection interval for top query collection specifically
      allowed_comment_keys: [application]        # keys to extract from leading SQL comments (see SQL Comment Extraction below)
    query_sample_collection:                     # this collection exports the currently (relate to the query time) executing queries as logs
      max_rows_per_query: 100                     # the maximum number of samples to bre reported.
      allowed_comment_keys: [application]        # keys to extract from leading SQL comments (see SQL Comment Extraction below)
    session_wait_event_collection:               # this collection exports per-session wait event statistics from v$session_event as logs
      max_rows_per_query: 100                    # the maximum number of session wait event rows to be reported                 

SQL Comment Extraction

When the db.server.query_sample and/or db.server.top_query events are enabled, the receiver can extract key-value pairs from leading SQL block comments (/* key=value */) and emit them as the db.query.comment_tags attribute on the corresponding logs.

This behavior is controlled by the allowed_comment_keys option, which can be set independently under top_query_collection and query_sample_collection:

• allowed_comment_keys (default = []): A list of comment keys to extract. For each enabled collection, only keys present in this allowlist are extracted from the leading SQL comment and included (as comma-separated key=value pairs) in the db.query.comment_tags attribute.

Extraction is disabled unless explicitly configured:

• When allowed_comment_keys is empty or unset, no comments are extracted.
• Only keys included in the allowlist are emitted; all other comment keys are ignored.
• Only leading block comments are parsed; comments elsewhere in the query are ignored.

Example:

receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
    top_query_collection:
      allowed_comment_keys: [application, team]
    query_sample_collection:
      allowed_comment_keys: [application, team]

Given a query such as /* application=exampleApp,team=payments */ SELECT * FROM users, the emitted log record will include db.query.comment_tags set to application=exampleApp,team=payments. When multiple keys are extracted, they are emitted as a comma-separated list of key=value pairs.

See documentation for details on the db.query.comment_tags attribute.

Documentation

Overview

Package oracledbreceiver implements a receiver collecting metrics from an Oracle datase.

Index

• func NewFactory() receiver.Factory
• type Config
  • func (c Config) Validate() error
• type QuerySample
• type SessionWaitEvent
• type TopQueryCollection

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a new Oracle receiver factory.

Types

type Config

type Config struct {
	DataSource                     string `mapstructure:"datasource"`
	Endpoint                       string `mapstructure:"endpoint"`
	Password                       string `mapstructure:"password"`
	Service                        string `mapstructure:"service"`
	Username                       string `mapstructure:"username"`
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	metadata.MetricsBuilderConfig  `mapstructure:",squash"`
	metadata.LogsBuilderConfig     `mapstructure:",squash"`

	TopQueryCollection `mapstructure:"top_query_collection"`
	QuerySample        `mapstructure:"query_sample_collection"`
	SessionWaitEvent   `mapstructure:"session_wait_event_collection"`
}

func (Config) Validate

func (c Config) Validate() error

type QuerySample

type QuerySample struct {
	MaxRowsPerQuery    uint64   `mapstructure:"max_rows_per_query"`
	AllowedCommentKeys []string `mapstructure:"allowed_comment_keys"`
	// contains filtered or unexported fields
}

type SessionWaitEvent

type SessionWaitEvent struct {
	MaxRowsPerQuery uint64 `mapstructure:"max_rows_per_query"`
	// contains filtered or unexported fields
}

type TopQueryCollection

type TopQueryCollection struct {
	MaxQuerySampleCount uint          `mapstructure:"max_query_sample_count"`
	TopQueryCount       uint          `mapstructure:"top_query_count"`
	CollectionInterval  time.Duration `mapstructure:"collection_interval"`
	AllowedCommentKeys  []string      `mapstructure:"allowed_comment_keys"`
}