ttExporter

The TimesTen Exporter converts TimesTen metrics into the form used by Prometheus. This integration enables you to add TimesTen to the systems that you monitor with Prometheus.

For information on configuring Prometheus and details on the metrics monitored and how to view the metrics, see The TimesTen Prometheus Exporter in Oracle TimesTen In-Memory Database Monitoring and Troubleshooting Guide.

Required Privilege

The operating system user must match a user in each TimesTen database in the instance that Prometheus monitors. If you run ttExporter as the instance administrator user, no further privilege is required. If, however, you wish to run ttExporter as a different operating system user, then that user must exist in each TimesTen database in the instance monitored by Prometheus. In addition, the operating system user must be granted the CREATE SESSION privilege. For example, if you want the osuser1 operating system user to run ttExporter, then you must do the following in each TimesTen database in the instance monitored by Prometheus:

Command> CREATE USER osuser1 IDENTIFIED EXTERNALLY;

User created.

Command> GRANT CREATE SESSION TO osuser1;

Usage in TimesTen Scaleout and TimesTen Classic

This utility is supported in both TimesTen Classic and TimesTen Scaleout.

In TimesTen Scaleout, the Exporter is supported on each host that is running either a data instance or a management instance. If there are multiple data instances on a single host, deploy one Exporter for each data instance.

Syntax

ttExporter -h | -help

ttExporter -create-server-certificate [-rsa-key-size bits][-certificate-common-name dnsip1] [-certificate-alt-names dnsip2]  [-certificate-directory mycertdir]

ttExporter -export-server-certificate serverfilename [-certificate-directory mycertdir]

ttExporter -export-client-certificate clientfilename -export-client-private-key keyfile 
  [-certificate-directory mycertdir]

ttExporter [-insecure] [-limit-rate r] -port p [-pid-file pidfilename] [-d]
  [-certificate-directory mycertdir]

Options

ttExporter has these options:

Option	Description
`-h` `-help`	Prints a usage message and exits.
`-certificate-directory mycertdir`	Defines the directory where an Oracle Wallet containing certificate information used by the Exporter is stored. (`mycertdir` is the location of the directory in this example.) If you specify `-certificate-directory`, you must specify this option for all invocations of `ttExporter`. This includes when creating a server certificate, when exporting a server certificate, when creating and exporting both a client certificate and a client private key, and when starting the Exporter. If you do not specify a directory, the certificates are stored in an Oracle Wallet in the home directory (`$HOME`) of the user.
`-create-server-certificate [-rsa-key-size bits]`	Creates a new server certificate. The Exporter uses the server certificate to authenticate itself to clients and to authenticate client certificates. Creating a new server certificate invalidates any previously exported client certificates. The key size specified by `-rsa-key-size` can be a bit count value of `2048` or larger. If not specified, the default is `2048`. The `-rsa-key-size` option is not required. Specifying this option does not start the Exporter.
`[-certificate-common-name dnsip1]` `[-certificate-alt-names dnsip2]`	Defines additional options for creating a server certificate. Must be used with the `-create-server-certificate` option. If you are using the Exporter with the TimesTen Kubernetes Operator, the `-certificate-common-name` and `-certificate-alt-names` options are required. See Create Your Own Oracle Wallet, Certificates, and Kubernetes Secrets and Create Certificates in the Oracle TimesTen In-Memory Database Kubernetes Operator User's Guide for usage and examples. The `-certificate-common-name dnsip1` option lets you specify a Common Name (CN) for the certificate. It matches the DNS name or the IP address where the certificate is installed. This CN can contain only one name. Single-level wildcards are acceptable. Replace the dnsip1 variable with this CN. The `-certificate-alt-names dnsip2` option lets you specify a Subject Alternative Name (SAN). This is a structured way to indicate all of the domain names and IP addresses that are secured by and included in the certificate. Replace the dnsip2 variable with this SAN. The SAN includes the CN mentioned previously as well as any other DNS names or IP addresses that need access to the TimesTen Exporter. Single level wildcards are acceptable.
`-d`	Starts the Exporter in debug mode and writes log messages to standard output instead of `syslog`. (Log messages are written to `syslog` by default.)
`-export-server-certificate serverfilename`	Exports the server certificate in PEM format. This example exports the certificate to the `serverfilename` file. Specifying this option does not start the Exporter.
`-export-client-certificate clientfilename -export-client-private-key keyfile`	Creates and exports the client certificate to a file ( `clientfilename`, in this example) and the client private key to a file (`keyfile`, in this example). You must specify these two options together. Specifying this option does not start the Exporter.
`-insecure`	Starts the exporter in insecure mode (no authentication), using the HTTP protocol. In this mode, the exporter does not authenticate itself using its server certificate and does not authenticate client certificates.
`-limit-rate r`	Sets the limit of HTTP (or HTTPS) `GET` requests per minute, where `r` equals the number of requests. The value of `r` can be any integer value from 1 to 15. If this option is not specified, the Exporter responds to at most 10 HTTP (or HTTPS) `GET` requests per minute.
`-pid-file pidfilename`	When starting the Exporter, you can optionally specify the `-pid-file` option. If specified, `ttExporter` writes its process ID into a file (`pidfilename`, in this example). You can then stop the Exporter by terminating the process ID stored in this file. This is an alternative to stopping the Exporter with a `SIGINTR` or `SIGTERM` signal.
`-port p`	Sets the listening port number (`p`, in this example) for the Exporter. You must set the port number whenever starting the Exporter.

Examples

To start the Exporter without authentication, use:

% ttExporter -insecure -port 12345

To use client certificate authentication:

Create a server certificate one time. Store the certificate in an Oracle Wallet located in the directory specified by -certificate-directory. The directory is mycertdir in this example:

% ttExporter -create-server-certificate -certificate-directory mycertdir

After creating the server certificate, export it in PEM format to a file. The -certificate-directory option must be specified (as it was specified when you created the server certificate):

% ttExporter -export-server-certificate mycertdir/server.crt -certificate-directory mycertdir

After exporting the server certificate, create and export both a client certificate and a client private key. You must create and export a client certificate and a client private key for each Prometheus instance that scrapes metrics from the Exporter. The -certificate-directory option must be specified (as it was specified when you created the server certificate):

% ttExporter -export-client-certificate mycertdir/client.crt 
    -export-client-private-key mycertdir/key.crt -certificate-directory mycertdir

After creating and exporting the client certificate and the client private key, start the Exporter. Supply the -pid-file option if you want ttExporter to write its process ID into a file (/tmp/ttexporter.pid, in this example). The -certificate-directory option must be specified (as it was specified when you created the server certificate):

% ttExporter -port 12345 -pid-file /tmp/ttexporter.pid -certificate-directory mycertdir