• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..23-Dec-2021-

README.mdH A D03-May-20229.2 KiB226170

config.goH A D23-Dec-20212.6 KiB8133

conn.goH A D23-Dec-20217.4 KiB278193

conn_test.goH A D23-Dec-20215.4 KiB187137

handler_archive.goH A D23-Dec-20211.7 KiB6437

handler_archive_discovery.goH A D23-Dec-20211.4 KiB6134

handler_asm_diskgroups.goH A D23-Dec-20211.7 KiB6538

handler_asm_diskgroups_discovery.goH A D23-Dec-20211.3 KiB5730

handler_cdb.goH A D23-Dec-20212 KiB8457

handler_custom_query.goH A D23-Dec-20212.1 KiB8447

handler_databases_discovery.goH A D23-Dec-20211.4 KiB5831

handler_datafiles.goH A D23-Dec-20211.3 KiB4822

handler_fra.goH A D23-Dec-20212.3 KiB11072

handler_instance.goH A D23-Dec-20211.7 KiB5630

handler_pdb.goH A D23-Dec-20211.6 KiB6538

handler_pdb_discovery.goH A D23-Dec-20211.3 KiB5730

handler_pga.goH A D23-Dec-20211.2 KiB4822

handler_ping.goH A D23-Dec-20211.3 KiB4921

handler_processes.goH A D23-Dec-20211.2 KiB4822

handler_redolog.goH A D23-Dec-20211.3 KiB5024

handler_sessions.goH A D23-Dec-20212.9 KiB137103

handler_sga.goH A D23-Dec-20212.2 KiB10773

handler_sysmetrics.goH A D23-Dec-20211.8 KiB7442

handler_sysparams.goH A D23-Dec-20211.3 KiB5024

handler_tablespaces.goH A D23-Dec-20214.6 KiB169139

handler_tablespaces_discovery.goH A D23-Dec-20211.4 KiB5428

handler_user.goH A D23-Dec-20211.6 KiB6234

metrics.goH A D23-Dec-20218 KiB213158

oracle.goH A D23-Dec-20213.1 KiB12574

oracle_test.goH A D23-Dec-20215.8 KiB213163

README.md

1# Oracle Database plugin
2Provides native Zabbix solution for monitoring Oracle Database (multi-model database management system).
3It can monitor several Oracle instances simultaneously, remote or local to the Zabbix Agent.
4The plugin keeps connections in the open state to reduce network congestion, latency, CPU and
5memory usage. Best for use in conjunction with the official
6[Oracle template.](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/db/oracle_agent2)
7You can extend it or create your template for your specific needs.
8
9## Requirements
10* Zabbix Agent 2
11* Go >= 1.13 (required only to build from source)
12* Oracle Instant Client >= 12
13
14## Supported versions
15* Oracle Database 12c2
16* Oracle Database 18c
17* Oracle Database 19c
18
19## Installation
20* [Install Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html)
21* Create an Oracle DB user and grant permissions
22```
23CREATE USER zabbix_mon IDENTIFIED BY <PASSWORD>;
24-- Grant access to the zabbix_mon user.
25GRANT CONNECT, CREATE SESSION TO zabbix_mon;
26GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS TO zabbix_mon;
27GRANT SELECT ON DBA_TABLESPACES TO zabbix_mon;
28GRANT SELECT ON DBA_USERS TO zabbix_mon;
29GRANT SELECT ON SYS.DBA_DATA_FILES TO zabbix_mon;
30GRANT SELECT ON V$ACTIVE_SESSION_HISTORY TO zabbix_mon;
31GRANT SELECT ON V$ARCHIVE_DEST TO zabbix_mon;
32GRANT SELECT ON V$ASM_DISKGROUP TO zabbix_mon;
33GRANT SELECT ON V$DATABASE TO zabbix_mon;
34GRANT SELECT ON V$DATAFILE TO zabbix_mon;
35GRANT SELECT ON V$INSTANCE TO zabbix_mon;
36GRANT SELECT ON V$LOG TO zabbix_mon;
37GRANT SELECT ON V$OSSTAT TO zabbix_mon;
38GRANT SELECT ON V$PGASTAT TO zabbix_mon;
39GRANT SELECT ON V$PROCESS TO zabbix_mon;
40GRANT SELECT ON V$RECOVERY_FILE_DEST TO zabbix_mon;
41GRANT SELECT ON V$RESTORE_POINT TO zabbix_mon;
42GRANT SELECT ON V$SESSION TO zabbix_mon;
43GRANT SELECT ON V$SGASTAT TO zabbix_mon;
44GRANT SELECT ON V$SYSMETRIC TO zabbix_mon;
45GRANT SELECT ON V$SYSTEM_PARAMETER TO zabbix_mon;
46```
47* Make sure a TNS Listener and an Oracle instance are available for connection.
48
49## Configuration
50The Zabbix agent 2 configuration file is used to configure plugins.
51
52**Plugins.Oracle.CallTimeout** — The maximum time in seconds for waiting when a request has to be done.
53*Default value:* equals the global Timeout configuration parameter.
54*Limits:* 1-30
55
56**Plugins.Oracle.ConnectTimeout** — The maximum time in seconds for waiting when a connection has to be established.
57*Default value:* equals the global Timeout configuration parameter.
58*Limits:* 1-30
59
60**Plugins.Oracle.CustomQueriesPath** — Full pathname of a directory containing *.sql* files with custom queries.
61*Default value:* — (the feature is disabled by default)
62
63**Plugins.Oracle.KeepAlive** — Sets a time for waiting before unused connections will be closed.
64*Default value:* 300 sec.
65*Limits:* 60-900
66
67### Configuring connection
68A connection can be configured using either keys' parameters or named sessions.
69
70*Notes*:
71* It is not possible to mix configuration using named sessions and keys' parameters simultaneously.
72* You can leave any connection parameter empty, a default hard-coded value will be used in the such case.
73* Embedded URI credentials (userinfo) are forbidden and will be ignored. So, you can't pass the credentials by this:
74
75      oracle.ping[tcp://USER:password@127.0.0.1/XE] — WRONG
76
77  The correct way is:
78
79      oracle.ping[tcp://127.0.0.1,USER,password,XE]
80
81* The only supported network schema for a URI is "tcp".
82Examples of valid URIs:
83    - tcp://127.0.0.1:1521
84    - tcp://localhost
85    - localhost
86* Only uppercase usernames are supported.
87
88#### Using keys' parameters
89The common parameters for all keys are: [ConnString][,User][,Password][,Service]
90Where ConnString can be either a URI or a session name.
91ConnString will be treated as a URI if no session with the given name is found.
92If you use ConnString as a session name, just skip the rest of the connection parameters.
93
94#### Using named sessions
95Named sessions allow you to define specific parameters for each Oracle instance. Currently, there are only four
96supported parameters: Uri, User, Password and Service.
97It's a bit more secure way to store credentials compared to item keys or macros.
98
99E.g: suppose you have two Oracle instances: "Oracle12" and "Oracle19".
100You should add the following options to the agent configuration file:
101
102    Plugins.Oracle.Sessions.Oracle12.Uri=tcp://192.168.1.1:1521
103    Plugins.Oracle.Sessions.Oracle12.User=<USERFORORACLE12>
104    Plugins.Oracle.Sessions.Oracle12.Password=<PasswordForOracle12>
105    Plugins.Oracle.Sessions.Oracle12.Service=orcl
106
107    Plugins.Oracle.Sessions.Oracle19.Uri=tcp://192.168.1.2:1521
108    Plugins.Oracle.Sessions.Oracle19.User=<USERFORORACLE19>
109    Plugins.Oracle.Sessions.Oracle19.Password=<PasswordForOracle19>
110    Plugins.Oracle.Sessions.Oracle19.Service=orcl
111
112Then you will be able to use these names as the 1st parameter (ConnString) in keys instead of URIs, e.g:
113
114    oracle.ping[Oracle12]
115    oracle.ping[Oracle19]
116
117*Note*: sessions names are case-sensitive.
118
119## Supported keys
120**oracle.diskgroups.stats[\<commonParams\>]** — Returns ASM disk groups statistics.
121
122**oracle.diskgroups.discovery[\<commonParams\>]** — Returns list of ASM disk groups in LLD format.
123
124**oracle.archive.info[\<commonParams\>]** — Returns archive logs statistics.
125
126**oracle.archive.discovery[\<commonParams\>]** — Returns list of archive logs in LLD format.
127
128**oracle.cdb.info[\<commonParams\>]** — Returns CDBs info.
129
130**oracle.custom.query[\<commonParams\>,queryName[,args...]]** — Returns result of a custom query.
131*Parameters:*
132queryName (required) — name of a custom query (must be equal to a name of a sql file without an extension).
133args (optional) — one or more arguments to pass to a query.
134
135**oracle.datafiles.stats[\<commonParams\>]** — Returns data files statistics.
136
137**oracle.db.discovery[\<commonParams\>]** — Returns list of databases in LLD format.
138
139**oracle.fra.stats[\<commonParams\>]** — Returns FRA statistics.
140
141**oracle.instance.info[\<commonParams\>]** — Returns instance stats.
142
143**oracle.pdb.info[\<commonParams\>]** — Returns PDBs info.
144
145**oracle.pdb.discovery[\<commonParams\>]** — Returns list of PDBs in LLD format.
146
147**oracle.pga.stats[\<commonParams\>]** — Returns PGA statistics.
148
149**oracle.ping[\<commonParams\>]** — Tests if connection is alive or not.
150*Returns:*
151- "1" if a connection is alive.
152- "0" if a connection is broken (if there is any error presented including AUTH and configuration issues).
153
154**oracle.proc.stats[\<commonParams\>]** — Returns processes statistics.
155
156**oracle.redolog.info[\<commonParams\>]** — Returns log file information from the control file.
157
158**oracle.sga.stats[\<commonParams\>]** — Returns SGA statistics.
159
160**oracle.sessions.stats[\<commonParams\>,[lockMaxTime]]** — Returns sessions statistics.
161*Parameters:*
162lockMaxTime (optional) — maximum session lock duration in seconds to count the session as a prolongedly locked.
163Default: 600 seconds.
164
165**oracle.sys.metrics[\<commonParams\>[,duration]]** — Returns a set of system metric values.
166*Parameters:*
167duration (optional) — capturing interval in seconds of system metric values. Possible values:
16860 — long duration (default).
16915 — short duration.
170
171**oracle.sys.params[\<commonParams\>]** — Returns a set of system parameter values.
172
173**oracle.ts.stats[\<commonParams\>]** — Returns tablespaces statistics.
174
175**oracle.ts.discovery[\<commonParams\>]** — Returns list of tablespaces in LLD format.
176
177**oracle.user.info[\<commonParams\>[,username]]** — Returns user information.
178*Parameters:*
179username (optional) — a username for which the information is needed. Lowercase user names are not supported.
180Default: current user.
181
182## Custom queries
183It's possible to extend functionality of the plugin using user-defined queries. To do that you should place all your
184queries in a directory specified in Plugins.Oracle.CustomQueriesPath (there is no default path) as *.sql files.
185For example, you have a tree:
186
187    /etc/zabbix/oracle/sql/
188    ├── long_tx.sql
189    ├── payment.sql
190    └── top_proc.sql
191
192You should set Plugins.Oracle.CustomQueriesPath=/etc/zabbix/oracle/sql
193
194So, when the queries are in place, you can execute them:
195
196    oracle.custom.query[<commonParams>,top_proc]
197    oracle.custom.query[<commonParams>,long_tx,600]
198
199You can pass as many parameters to a query as you need.
200The syntax for placeholder parameters uses ":#", where "#" is an index number of a parameter.
201E.g:
202```
203/* payment.sql */
204
205SELECT
206    amount
207FROM
208    payment
209WHERE
210    user = :1
211    AND service_id = :2
212    AND date = :3
213```
214
215    oracle.custom.query[<commonParams>,payment,"John Doe",1,"10/25/2020"]
216
217## Current limitations
218* Connection by SID is not supported.
219* Only uppercase usernames are supported.
220
221## Troubleshooting
222The plugin uses Zabbix agent's logs. You can increase debugging level of Zabbix Agent if you need more details about
223what is happening.
224The environment variable DPI_DEBUG_LEVEL can be used to selectively turn on the printing of various logging messages
225from ODPI-C. See [ODPI-C Debugging](https://oracle.github.io/odpi/doc/user_guide/debugging.html) for details.
226