Provides a web interface for managing the Inscope Metrics stack. This includes viewing telemetry (aka streaming statistics) from one or more hosts running Metrics Aggregator Daemon. The web interface also provides a feature for browsing hosts reporting metrics, viewing and editing alerts, scheduling and delivering reports and performing roll-ups in KairosDb.
Clone the repository and build the source. The artifacts from the build are in target/metrics-portal-${VERSION}-bin.tgz
where ${VERSION} is the current build version. To install, copy the artifact directories recursively into an
appropriate target directory on your Metrics Portal host(s). For example:
metrics-portal> ./jdk-wrapper.sh ./mvnw package -Pno-docker
metrics-portal> scp -r target/metrics-portal-${VERSION}-bin.tgz my-host.example.com:/opt/metrics-portal/
Additionally, Metrics Portal releases a tar.gz package of its build artifacts which may be obtained from Github releases. To install,
download the archive and explode it. Replace ${VERSION} with the release version of Metrics Portal you are installing.
For example, if your Metrics Portal host(s) have Internet access you can install directly:
> ssh -c 'curl -L https://github.com/ArpNetworking/metrics-portal/releases/download/v${VERSION}/metrics-portal-${VERSION}-bin.tgz | tar -xz -C /var/tmp/metrics-portal/' my-host.example.com
Otherwise, you will need to download locally and distribute it before installing. For example:
> curl -L https://github.com/ArpNetworking/metrics-portal/releases/download/v${VERSION}/metrics-portal-${VERSION}-bin.tgz -o /var/tmp/metrics-portal.tgz
> scp /var/tmp/metrics-portal.tgz my-host.example.com:/var/tmp/
> ssh -c 'tar -xzf /var/tmp/metrics-portal.tgz -C /opt/metrics-portal/' my-host.example.com
Alternatively, each release of Metrics Portal also creates an RPM which is available on Github releases. To install, download the RPM and install it. For example, if your Metrics Portal host(s) have Internet access you can install directly:
> ssh -c 'sudo rpm -i https://github.com/ArpNetworking/metrics-portal/releases/download/v${VERSION}/metrics-portal-${VERSION}-1.noarch.rpm' my-host.example.com
Otherwise, you will need to download the RPM locally and distribute it before installing. For example:
> curl -L https://github.com/ArpNetworking/metrics-portal/releases/download/v${VERSION}/metrics-portal-${VERSION}-1.noarch.rpm -o /var/tmp/metrics-portal.rpm
> scp /var/tmp/metrics-portal.rpm my-host.example.com:/var/tmp/
> ssh -c 'rpm -i /var/tmp/metrics-portal.rpm' my-host.example.com
Please note that if your organization has its own authorized package repository you will need to work with your system administrators to install the Metrics Portal RPM into your package repository for installation on your Metrics Portal host(s).
Furthermore, if you use Docker each release of Metrics Portal also publishes a Docker image that you can either install directly or extend.
If you install the image directly you will likely need to mount either a local directory or data volume with your organization specific configuration.
If you extend the image you can embed your configuration file directly in your Docker image.
Regardless, you can override the provided configuration by first importing
portal.application.conf in your configuration file like this:
include required("portal.application.conf")
Next set the METRICS_PORTAL_CONFIG environment variable to -Dconfig.file="your_file_path" like this:
docker run ... -e 'METRICS_PORTAL_CONFIG=-Dconfig.file="/opt/metrics-portal/config/custom.conf"' ...
In addition to METRICS_PORTAL_CONFIG, you can specify:
LOGBACK_CONFIG- Location of Logback configuration XML; default is-Dlogger.file=/opt/metrics-portal/config/logback.xmlJVM_XMS- Java initial memory allocation; default is64mJVM_XMX- Java maximum memory allocation; default is1024mJAVA_OPTS- Additional Java arguments; many arguments are passed by https://github.com/ArpNetworking/metrics-portal/blob/master/main/docker/Dockerfile.
Regardless of your installation method, in the installation's bin sub-directory there is a script to start the Metrics
Portal: metrics-portal. This script should be executed on system start with appropriate parameters. In general:
/opt/metrics_portal/bin/metrics-portal <JVM ARGS> -- <APP ARGS>
For example:
/opt/metrics_portal/bin/metrics-portal -Xms512m -- /opt/metrics-portal
Arguments before the -- are interpreted by the JVM while arguments after -- are passed to Metrics Portal.
If you have reporting enabled (reports.enabled = true in portal.application.conf), and you want to render web-based reports, you will need to have Chrome or Chromium installed alongside Metrics Portal, and set the chromePath configuration for those renderers to point to the appropriate executable file.
If you installed Metrics Portal using a Docker image then execution is very simple. In general:
docker run -p 8080:8080 <DOCKER ARGS> arpnetworking/metrics-portal
For example:
docker run -p 8080:8080 -e 'JAVA_OPTS=-Xms512m' arpnetworking/metrics-portal
The section above on Docker installation covers how to pass arguments in more detail.
Aside from the JVM command line arguments, you may provide two additional configuration files.
The first is the LogBack configuration file. To use a custom logging configuration simply pass the following argument to the JVM:
-Dlogger.file=/opt/metrics-portal/custom-logger.xml
Where /opt/metrics_portal/custom-logger.xml is the path to your logging configuration file. Please refer to
LogBack documentation for more information on how to author a configuration file.
Installation via RPM or Docker will use the production file logging configuration file by default. However, other installation methods will use the debugging logging configuration file by default and users are strongly recommended to override this behavior.
Metrics Portal ships with a second production console logging configuration file which outputs to standard out instead of to a rotated and gzipped file.
The second configuration file is for the application. To use a custom configuration simply pass the following argument to the JVM:
-Dconfig.file=/opt/metrics_portal/custom.conf
Where /opt/metrics_portal/custom.conf is the path to your application configuration file.
Installation via RPM or Docker will use the included default application configuration file. This configuration documents and demonstrates many of the configuration options available.
To use the default application configuration file for non-RPM and non-Docker installations use a command like this:
/opt/metrics_portal/bin/metrics-portal -Dconfig.resource=conf/portal.application.conf -- /opt/metrics-portal
Metrics Portal ships with two additional application configuration files, [postgresql.application.conf](conf/postgresql.application.conf)
for using Postgresql as the data store and another [cassandra.application.conf](conf/cassandra.application.conf)
for using Cassandra as the data store. You can specify one of these by adding the following
to argument to the JVM:
For Postgresql: -Dconfig.resource=conf/postgresql.application.conf
For Cassandra: -Dconfig.resource=conf/cassandra.application.conf
Both of these configuration files derive from the base configuration file, and it is recommended that you use one of these as your base configuration. Additionally, both support overrides for locating the specific data store instance. Please refer to these files when configuring your Metrics Portal instance.
Finally, while it is possible to leverage the provided configuration files, it is strongly recommended that users author a custom application configuration and that you inherit from the default application configuration file and provide any desired configuration as overrides. Please refer to Play Framework documentation for more information on how to author a configuration file.
The Metrics Portal project intentionally uses a custom default application configuration and custom default routes specification. This allows projects extending the Metrics Portal to supplement functionality more easily with the standard default application configuration and routes. To use these files as extensions rather than replacements you should make the following changes.
First, add dependencies on the Metrics Portal code and assets in conf/Build.scala:
"com.arpnetworking.metrics" %% "metrics-portal" % "VERSION"
Second, your extending project's application configuration should include one of the custom default configuration in conf/application.conf:
Base:
include "portal.application.conf"
Postgresql:
include "postgresql.application.conf"
Cassandra:
include "cassandra.application.conf"
Third, your extending project's application configuration should restore the default router in conf/application.conf:
application.router = null
Finally, your extending project's routes specification should include the custom default routes in conf/routes:
-> / portal.Routes
Prerequisites:
Building:
metrics-portal> ./jdk-wrapper.sh ./mvnw verify
Building without Docker (will disable integration tests):
metrics-portal> ./jdk-wrapper.sh ./mvnw -Pno-docker verify
To control which verification targets (e.g. Checkstyle, Findbugs, Coverage, etc.) are run please refer to the
parent-pom for parameters (e.g. -DskipAllVerification=true).
When launching Metrics Portal via Play (e.g. play2:run) there is limited support for automatic recompiling and
reloading of assets (e.g. HTML, Typescript, etc.).
To run the server on port 8080 and its dependencies launched via Docker:
metrics-portal> ./jdk-wrapper.sh ./mvnw docker:start
To stop the server and its dependencies run; this is recommended in place of docker kill as it will also remove the
container and avoids name conflicts on restart:
metrics-portal> ./jdk-wrapper.sh ./mvnw docker:stop
To run the server on port 8080 without dependencies via Play; you need to configure/provide/launch dependencies manually (see below):
metrics-portal> ./jdk-wrapper.sh ./mvnw play2:run -Dconfig.resource=postgresql.application.conf -Dpostgres.port=6432
To debug on port 9002 with the server on port 8080 and its dependencies launched via Docker:
metrics-portal> ./jdk-wrapper.sh ./mvnw -Ddebug=true docker:start
To debug on port 9002 with the server on port 8080 via Play; you need to configure/provide/launch dependencies manually (see below):
metrics-portal> MAVEN_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9002" ./jdk-wrapper.sh ./mvnw play2:run -Dconfig.resource=postgresql.application.conf -Dpostgres.port=6432
To launch dependencies only via Docker:
metrics-portal> ./jdk-wrapper.sh ./mvnw docker:start -PdependenciesOnly
To execute unit performance tests:
metrics-portal> ./jdk-wrapper.sh ./mvnw -PperformanceTest test
^ TODO(ville): This is not yet implemented.
To execute integration performance tests:
metrics-portal> ./jdk-wrapper.sh ./mvnw -PperformanceTest verify
^ TODO(ville): This is not yet implemented.
To use the local version as a dependency in your project you must first install it locally:
metrics-portal> ./jdk-wrapper.sh ./mvnw install
- Unit tests (
test/java/**/*Test.java) may be run or debugged directly from your IDE. - Integration tests may be run or debugged directly from your IDE provided an instance of Metrics Portal and its dependencies are running locally on the default ports.
- To debug Metrics Portal while executing an integration test against it simply launch Metrics Portal for debug, then attach your IDE and finally run/debug the integration test from your IDE.
- To run tests in your IDE which rely on EBean classes, you must first run
./jdk-wrapper.sh ./mvnw process-classeson the command line to enhance the Ebean classes.
(See also the list of debug flags in the Building section.)
- Debugging Chrome-based reports. With the default options in
portal.application.conf, Chrome offers a remote debugger on port 48928, which you can access by visiting chrome://inspect in another Chrome instance and addinglocalhost:48928under "Discover network targets".
If you have write-access to this repository, you should just be able to cut a release by running git checkout master && git pull && mvn release:prepare, and accepting the default version-names it proposes.
The project can be imported normally using "File / New / Project From Existing Sources..." using the Maven aspect.
However, you will first need to mark the target/twirl/main directory as a generated source directory. Next, to reflect
changes to the templates within IntelliJ you will need to generate them from the command line using ./jdk-wrapper.sh ./mvnw compile
(do so now). Finally, under "Module Settings", then under "Platform Settings" / "Global Libraries", you need to click "+", choose
"Scala SDK" and choose "Maven 2.11.12" and click "OK" and "OK" again. This should enable discovery of the generated code and
its compilation using scalac for use in the IDE (e.g. for running tests).
Published under Apache Software License 2.0, see LICENSE
© Groupon Inc., 2014