Documentation relative to Release: 1.2. 1.2.

2 Authors: Andrea Dalle Vacche Jason Chatfield

Download & Installation Instructions

About Orabbix
Product Description
Orabbix is a plugin designed to work with Zabbix Enterprise Monitor to provide multi%tiered multi monitoring, performance and availability reporting and measurement for Oracle Databases, along with server performance metrics. t provides an effective mechanism to ac!uire data from numerous Oracle instances, and in turn provides this information for monitoring and performance metrics to your Zabbix Zabbix server. $ou can then utili'e the reporting capabilities of Zabbix for all data collected, cted, and provide analysis such as graphs and service level agreement metrics for stakeholders. "he current distribution contains a set of pre%defined pre defined templates which incorporate alerting and graphing capabilities from initial deployment. #owever these can can be fine tuned to suit your needs and data&monitoring re!uirements.

JDBC

JDBC

Zabbix Protocol

JDBC

JDBC

Fig. 1 - Orabbix Architecture

What can it monitor?

(elow are some examples of what Orabbix is capable of monitoring) * D( +ersion ,i.e. +alidity of package* .rchiving ,.rchive log production with trend analysis* Event /aits ,0iles &O, single block read, multi%block read, direct path read, 1234et Messages, 5ontrol file &O, 3og /rite* #it 6atio ,#it 6atio on "riggers, "ables&7rocedures, 123 .rea, (ody* 3ogical &O ,1erver performance on 3ogical &O of) 5urrent 6ead, 5onsistent 6ead, (lock 5hange* 7hysical &O ,6edo /rites, Datafile /rites, Datafile 6eads* 78. * 18. , n particular9 0ixed (uffer, :ava 7ool, 3arge 7ool, 3og (uffer, 1hared 7oolm (uffer 5ache* 1hared 7ool ,7ool Dictionary 5ache, 7ool 0ree Memory, 3ibrary 5hache, 123 .rea, M 15.* 7in #it 6atio ,Oracle library cache pin are caused by contention with the library cache, the area used to store 123 executables for re%use* 1essions & 7rocesses * 1essions ,.ctive 1essions, nactive 1essions, 1ystem 1essions* D(1i'e&D(0ile1i'e ,D(1i'e si'e of database really used space and of 0ilesi'e-

Fig. 1 Archivelog

Fig. 2 - DBSize and DBFileSize

Fig. 4 SGA Fig. 3 - Events Waits

Fig. 6 Sessions

Fig. 5 - Hit Ratio

Fig. 3 - Pin Hit Ratio Fig. 72 - Shared Pool

Fig. 10 PGA Fig. 94 - Sessions Processes

Fig. 11 - Logical I/O

Orabbix Author
.ndrea Dalle +acche) http)&&www.smartmarmot.com

History
$ou can read about the history and evolution of the Orabbix plug%in in these threads below) Original here) http)&&www.'abbix.com&forum&showthread.php;t<=>??? 3atest here) http)&&www.'abbix.com&forum&showthread.php;t<=?>@=

Distribution
$ou can find the latest versions of Orabbix at the locations listed below) http)&&www.smartmarmot.com&product&orabbix&download& or https)&&sourceforge.net&proAects&orabbix&

Requirements
"o use Orabbix, you will re!uire the following on your Zabbix 1erver) * Zabbix =.B.x 1erver * :ava 6untime Environment ? 5urrent known successfully tested Oracle host platforms) * 6#E3C.D ,5entO1 C.E F C.C* /indows GHH> ,with :ava 1E =.?* #7%ID ==.>= * . D C.> 5urrently known tested Oracle +ersions) * =Hg * =H.G ** IMPORTANT** $ou do 4O" need to install an Oracle client of any kind for Orabbix to work. Orabbix uses :ava obAects and connection strings to connect to the Oracle Database, and as such doesnJt re!uire an Oracle client to be installed on your Zabbix 1erver.

Installation
Assumptions
"he installation instructions have been created based on instructions for most Knix deployments ,i.e. 6#E3&5entO1-, and is assumed that any alterations re!uired for your specific environment are to be taken into account accordingly. "his guide is based upon there being two ,G- #osts, =x Zabbix 1erver and =x Oracle 1erver. f you are planning on monitoring an Oracle instance that is running on your Zabbix 1erver, the steps are the same, with minor adAustments re!uired for your connection information.

"he steps also assume you are configuring Orabbix to monitor a new installation or setup of Oracle. "he installation steps will have you 86.4" access for the Zabbix user to all tables, and this will include any I1E6 tables present at the time of execution. f you do not want Zabbix to have access to specific tables or resources within your database, you will need to set a DE4$ to the Zabbix users access as re!uired. 5onsult your D(. for details, as this is beyond the scope of these instructions.

teps !or Installation

=. G. >. E. Download Orabbix to your Zabbix 1erver On your Zabbix server, un'ip Orabbix to) &opt&orabbix 5opy file &opt&orabbix&init.d&orabbix to &etc&init.d&orabbix 8rant execute permissions to the following files) * &etc&init.d&orabbix * &opt&orabbix&run.sh C. 5reate a Iser ,Z.(( D- for Orabbix to access your Oracle Database. $ou can use the following script)

CREATE USER ZABBIX IDENTIFIED BY <REPLACE WITH PASSWORD> DEFAULT TABLESPACE SYSTEM TEMPORARY TABLESPACE TEMP PROFILE DEFAULT ACCOUNT UNLOCK; 2 Roles for ZABBIX GRANT CONNECT TO ZABBIX; GRANT RESOURCE TO ZABBIX; ALTER USER ZABBIX DEFAULT ROLE ALL; 5 System Privileges for ZABBIX GRANT SELECT ANY TABLE TO ZABBIX; GRANT CREATE SESSION TO ZABBIX; GRANT SELECT ANY DICTIONARY TO ZABBIX; GRANT UNLIMITED TABLESPACE TO ZABBIX; GRANT SELECT ANY DICTIONARY TO ZABBIX;

** NOTE : f you are using Oracle ==g, you will need to add the following) exec dbms_network_acl_admin.create_acl(acl => resolve.xml,description => resolve acl, principal =>ZABBIX, is_grant => true, privilege => resolve); exec dbms_network_acl_admin.assign_acl(acl => resolve.xml, host =>*');

$ou can verify the above is correct by running) select utl_inaddr.get_host_name(127.0.0.1) from dual; ?. 0or this example on 6ed#at, run) chkconfig -add orabbix L. +erify with) chkconfig -list

B. 5reate a #ost entry in Zabbix for the D( nstance&s you are planning to monitor, and import the templates found at) &opt&orabbix&template KK 7lease note, instructions for step ,B- can be found in the Zabbix Manual at http)&&www.'abbix.com&documentation.php /ith this step ,B-, ensure the name of your host in Zabbix is the same name of the 1 D or Oracle instance name.

"on!i#uration
4ow we need to configure your Orabbix setup. "he tags below are listed as they will appear within the respective configuration files. "he first you will need to modify is your config.props file to define your connection properties for Zabbix and Oracle. "he config.props file can be found at /opt/orabbix/conf/config.props

$abbix er%er&ist
'comma separed list o! $abbix ser%ers "he settings under this tag allow you to configure your Zabbix 1erver information. Orabbix can also be configured to send your Oracle data to multiple Zabbix servers. TIP: This can be beneficial for distributed monitoring scenarios, server migrations or Orabbix data to a Disaster Recovery site or server. 6eplace with your Zabbix 1erver info where appropriate9 ZabbixServer ist!ZabbixServer"#ZabbixServer$ ZabbixServer".A%%ress!"&$."'(.)." ZabbixServer".Port!"))*" ZabbixServer$.A%%ress!"&$."'(.).$ ZabbixServer$.Port!"))*" replicating

OrabbixDaemon
Entries under this tag allow you to set your Orabbix Daemon parameters. '(ax)hread*umber should be +, than the number o! your databases 1et the number of threads the Orabbix Daemon should have inside his internal pool of D( :obs. "his number should be at least e!ual to ,or more than- then number of databases monitored by Orabbix, now this parameter if not set is automatically calculated. e.g. 0or CH Databases, we are using =HH threads Orabbix+ae,on.MaxT-rea%N.,ber!")) 'pid-ile 4ext you can set the location of the Daemons 7 D file. Default location is) &opt&orabbix&logs Orabbix+ae,on.Pi%/i0e!./0ogs/orabbix.pi% KK 4O"E) 6elative path is permitted here

TIP: With the features of the Orabbix Daemon, it is possible to clone Orabbix and use different configurations. As such, it is therefore possible to have one Daemon that checks your T !T databases, another iteration that checks your D " #O$% &T databases and a third that checks your $ROD'(T)O& databases, each *ith different timings and check loops+

Database&ist
'put here your databases in a comma separated list "his is where you define your database instances. $ou can specify more than one instance here, separated using a comma. +atabase ist!E1AMP E"#E1AMP E$ KK 4ote) "he names of the instances must match those you have specified as your #O1" name in Zabbix '"on!i#uration o! "onnection pool 0rom here, you will configure settings that are specific to the connection pool. .s the comments in config.props suggest, if you do not specify these values, Orabbix will use default values which have been hard%coded. '(aximum number o! acti%e connection inside pool 1et the maximum number of connections that can be allocated to this pool at any time,or alternatively set a negative value for no limit. +atabase ist.MaxActive!") ')he maximum number o! milliseconds #ere you define how long that the pool will wait ,when there are no available connections- for a connection to be returned before throwing an exception, or set the value M< H to wait indefinitely. +atabase ist.Max2ait!")) .lso under the same section, you can define the maximum number of connections that can remain idle within the connection pool, without being released. .lternatively, you can set a negative value for no limit. +atabase ist.MaxI%0e!" TIP: ,ou can specify the Database connection parameters for each database you *ish to monitor individually, underneath your Database (onnection $arameters. This allo*s you to customise your connection settings based on the Database constraints ).e one connection pool for your $ROD'(T)O& D- and another for you T !T D-, for example. D-/.%axActive0/1 D-/.%axWait0/11 D-/.%ax)dle0/ &ote that any settings defines this *ay *ill override the general settings for your generic connection pool.

Database "onnection Parameters

"his section sets your connection string to the Oracle Database. "his string invokes a :ava Database 5onnector ,:D(5- to your Oracle Databases, and as such does not need the Oracle 5lient to be installed. 'de!ine here your connection strin# !or each database #ere you will define the connection string. "hese are formatted as) D(4ame.Irl,as specified in your Database#ist- followed by the Adbc string and your Database 1erver information. E1AMP E./0rl02dbc3oracle3thin34! R" R/. 5A%$# .(O%3/67/3D-/ 1et your Database username and password below. e.g. E1AMP E".3ser!4abbix E1AMP E".Pass5or%!4abbix6pass5or% T)$3 !etting connections to multiple databases is made easy by adding more connection strings, *ith their corresponding credentials. xample given belo*.
E1AMP E$.3r0!7%bc:orac0e:t-in:8server$.%o,ain.exa,p0e.co,:9 ISTENER6PORT::E1AMP E$ E1AMP E$.3ser!4abbix E1AMP E$.Pass5or%!4abbix6pass5or% E1AMP E;.3r0!7%bc:orac0e:t-in:8server;.%o,ain.exa,p0e.co,:9 ISTENER6PORT::E1AMP E; E1AMP E;.3ser!4abbix E1AMP E;.Pass5or%!4abbix6pass5or%

KK 4ote) .fter these entries, you can set your Max.ctive, Max/ait and Max dle for the individual database connections if you so wish. "here is a pair of default parameter)
+efa.0t3ser ! 93SERNAME: +efa.0tPass5or% ! 9PASS2OR+:

this default parameter can be overridden using the following pair

9+<6NAME:.3ser an% 9+<6NAME:.3ser

t is only possible to override Isername or 7assword.

1uery &ist -ile

"his defines where the file containing the Oracle ,123- !ueries can be found. "his is a customisable file. $ou can find the !uery parameter file at) =.er> ist/i0e!/opt/orabbix/conf/?.er>.props you can also specify ) 9+<NAME:.=.er> ist/i0e!./conf=.er>Test.props t-is fi0e specif> t-e ?.er> fi0e of a %atabase re0ative pat- are a00o5e% T)$3 "his is really useful to use different !uery file for different databases or to have a pool of !uery file one for each Oracle 6elease ,if you have different release- and&or to have different !uery files for 7roduction environment, "est environment, Developement environment etc.. the following parameter
9+<6NAME:.Extra=.er> ist/i0e !!./conf=.er>Test6$.props

adds another custom !uery to the default !uery file. f there are duplicates the Extra2uery3ist0ile will override them.

"on!i#uration o! query/props !ile

"he !uery.props file can be modified or added to, so you can supply your own customised !ueries through Orabbix against your Oracle instances&databases. Each !uery created has an associated N temN or item name that Zabbix will use to identify the !uery. KK 4ote) tem names must be uni!ue. "he configurable items are formatted as follows. '1uery&ist $ou have to set the !uery name under the 2uery3ist in the !uery.props file. Each !uery name is comma separated. 0or example9 =.er> ist!?.er>Na,e"#?.er>Na,e$#?.er>Na,e; '1uery $ou must identify the !uery by the uni!ue item name you specified in the 2uery3ist, followed by N.2ueryN for Orabbix to recogni'e that this is the !uery string. ts important to remember 4O" to add the semi%colon O9P to the end of your custom !uery. c.sto,=.er>Ite,Na,e.=.er>!>o.r=.er>@ere 4ow you can define what you want Orabbix to return to your Zabbix 1erver if no data is found for your !uery. c.sto,=.er>Ite,Na,e.No+ata/o.n%!none T)$3 )n the example above, Orabbix *ould send the string 8none9 to the :abbix !erver.

$ou can specify if you want a different execution period for your !uery c.sto,=.er>Ite,Na,e.Perio%!9Express a perio% in ,in.te: T)$3,ou can change the execution time of dbversion that don;t change often 4ext you can specify a !uery that will be executed and if return Race(ondiftion"alue the !uery custom<uery)tem&ame is executed otherwise is skipped c.sto,=.er>Ite,Na,e.AATIBE!Ctr.eDfa0seE if true !uery is executed otherwise skipped

arc-ive.=.er>!se0ect ro.n%F A. OGS*<.ABG/")$H/")$H/") I fro, F SE EAT AO3NT F*I OGS /ROM BJ OG6@ISTORK 2@ERE /IRST6TIME :! Fs>s%ate L")/')/$HII A# F SE EAT AvgF<KTESI ABG# Ao.ntF"I# MaxF<KTESI Max6<>tes#MinF<KTESI Min6<>tes /ROM vJ0ogI < arc-ive.RaceAon%ition=.er>!se0ect va0.e fro, vJpara,eter 5-ere na,e!M0og6arc-ive6startM arc-ive.RaceAon%itionBa0.e!/A SE T)$3 )n the example above, Orabbix *ould execute 8archive.<uery9 only if the =uery 8archive.Race(ondition<uery9 return the value 8archive.Race(ondition"alue9. $ratically the 8Archive9 =uery is execute only if database is in arhivelogmode >$arameter 8log?archive?start9 set to TR' @ 9=.er>Na,e:.Tri,!Ctr.eDfa0seE if true the resultset is trimmed >default is true@

9=.er>Na,e:.A%%Spaces!Ctr.eDfa0seE if true the add a space bet*een columns of resultset>default is true@ 9=.er>Na,e:.Exc0.%eAo0.,ns ist!C"#$#;#..nE exclude from result set the /st, the 7nd etc.. columns from resultset 9=.er>Na,e:.Perio% 9=3ERK6NAME:.2-enNotA0ive ! 9BA 3E: is used to specify a value or a string to send if a database is not *orking, doing such *ill AcleanA the graphs generated in :abbix *ith a AsetA value.

Added the following parameter on main configuration file: DefaultUser = <USERNAME> Default assword = < ASS!"RD> 9 =.er>Na,e :.Extra=.er> ist/i0e ! 9BA 3E:

on #uer$%s properties file &%'e added the following parameter: <(UER)*NAME>+!henNotAli'e = <,A-UE> with these parameter $ou can define a default username and password for all the data.ase+ DefaultUser = <USERNAME> Default assword = < ASS!"RD> this default parameter can .e o'erridden using the couple <D/*NAME>+User and <D/*NAME>+User &s possi.le to o'erride onl$ Username or assword+ the following parameter <D/*NAME>+E0tra(uer$-ist1ile = add another custom #uer$ to a default #uer$ file+ if there are duplicate the E0tra(uer$-ist1ile will o'erride them+ the following parameter <(UER)*NAME>+!henNotAli'e = <,A-UE> is used to specif$ a 'alue or a string to send if a data.ase is not wor2ing3 doing so $ou are going to 4clean4 the graphs generated in 5a..i0 with a 4set4 'alue+

How to 0se Orabbix2-A1

How do I start2stop the Daemon?
"o start the Orabbix Daemon, simply run) /etc/init.%/orabbix start "o stop the Orabbix Daemon, simply run) /etc/init.%/orabbix start

How does &o##in# wor3?

"he Orabbix daemon outputs its log file to the default location of /opt/orabbix/0ogs/ 3ogging properties can be modified by making your re!uired changes to9 /opt/orabbix/conf/0ogH7.properties

"he property setting responsible for defining the output location is9 logB2.appender.Orabbix.Cile0logsDorabbix.log T)$3 Crom this properties file, you can modify the location, file name and log format as desired. Cor additional information, please refer to the official logB2 documentation, found at. http)&&logging.apache.org&logEA&=.G&index.html

Is there a way !or orabbix to connect to RA" or Data4uard?

,es is possible. e.g. )f you have t*o host RA(/ and RA(7 and one instance RA()&!T you should *rite the connection string as follo*3 RAAINST.3r0!7%bcrac0e:t-in:8F+ESARIPTION!FA++RESS6 IST!FA++RESS!FPROTOAO !TAPIF@O ST!RAA".E1AMP E.AOMIFPORT!"*$"IIFA++RESS!FPROTOAO !TAPIF@OST!RAA$.E1AMP E.AOM IFPORT!"*$"IIIFAONNEAT6+ATA!FSERBIAE6NAME!RAAINSTIII

What can I modi!y without restartin# the daemon?

"he parameters that are dynamically read at each iteration of OOrabbixDaemon.1leepP are as follows9 1..ny 2uery added to !uery.props 2.Modifications to config.props Available 'pcoming Release. To be advised 3.Database 3ist 5urrently, the only known items that donNt dynamically update are the :abbixDaemon.%axThread&umber, and changes to 5onnection 7ool info.

&I"5*"5 In!ormation
Orabbix is released under and according to the 4*0 45*5RA& P06&I" &I"5* 5 7ersion 89 :; <une :==>