Deploy instrumented applications
Overview
This guide takes you through the necessary steps to deploy your instrumented applications in:
- Kubernetes or OpenShift environment.
Deploy in Kubernetes or OpenShift
The first thing you need to do is instrument your application. Depending on the platform you are using, see the following documentation:
If you are collecting application logs, the application must log to standard output (stdout). Docker automatically captures stdout and stores it in a log file that the Collection Agent is configured to read from.
Create a Docker image for your application and push it to the Docker registry used by the Kubernetes or OpenShift cluster.
Deploy the application
In order for the application metrics to be properly collected, reported, and visualised, you must do the following:
- Define certain environment variables in the deployment manifest. The StatsD client library looks for the following variables and adds them as dimensions to each metric that is published:
NAMESPACE
andPOD_NAME
— the values for these can be populated automatically by the Kubernetes downward API. For more information, see the official Kubernetes documentation.CONTAINER_NAME
— not available through the API and can be specified manually.
- Provide the following coordinates of the StatsD server:
STATSD_SERVER
— since the StatsD server is running in the Netprobe for Orchestrated Environments DaemonSet, this variable can be populated using the downward API's hostIP property.STATSD_PORT
— only required if you are using a port other than the default8125
.
Example deployment
In this example, the application to deploy is called fixengine
. The deployment defines a pod with two containers, one named router
, and a sidecar named management-agent
.
- Create the deployment manifest:
apiVersion: apps/v1 kind: Deployment metadata: name: fixengine spec: selector: matchLabels: environment: prod replicas: 1 template: metadata: labels: environment: prod spec: containers: - name: router image: docker-registry.default.svc:5000/myproject/router env: - name: NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: CONTAINER_NAME value: "router" - name: STATSD_SERVER valueFrom: fieldRef: fieldPath: status.hostIP - name: management-agent image: docker-registry.default.svc:5000/myproject/management-agent env: - name: NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: CONTAINER_NAME value: "management-agent" - name: STATSD_SERVER valueFrom: fieldRef: fieldPath: status.hostIP
- Deploy the application:
# OpenShift: oc apply -f fixengine-deployment.yml -n myproject # Kubernetes: kubectl apply -f fixengine-deployment.yml -n myproject
Deploy in Pivotal Cloud Foundry
The end of support for Cloud Foundry plugin is 31 May 2021. This documentation is now archived and is no longer updated.
To deploy a Java application with the StatsD or JVM metrics library:
- Download the StatsD client from ITRS Downloads site or add it as a maven dependency.
<dependency> <groupId>com.itrsgroup.collection</groupId> <artifactId>statsd-client</artifactId> <version>1.0</version> </dependency>
- Instrument the application using StatsD client Java library. For more information, see StatsD client Java library.
- Compile and build the application to produce the JAR file.
- Create a PCF deployment manifest:
--- applications: - name: myapp # path to the jar created in the previous step path: target/myapp-1.0-jar-with-dependencies.jar buildpacks: - https://github.com/cloudfoundry/java-buildpack.git env: # hostname/address of the server running the Collection Agent STATSD_SERVER: 1.2.3.4 STATSD_PORT: 8125
- Log in to the PCF API using the following command (the API host may differ):
cf login -a api.run.pivotal.io
- Deploy the application with the manifest:
cf push -f myapp.yml
Metric dimensions
Metrics and other data points generated by an application deployed in the Pivotal Cloud Foundry are identified by the following dimensions:
Dimension | Example name |
---|---|
space_name
|
Name of the space where the application is deployed. |
application_name
|
Name assigned to the application when it was pushed. |
cf_instance_guid
|
UUID of the application instance to uniquely differentiate between multiple instances of scaled applications. |
cf_instance_index
|
Index number of the application instance to relatively differentiate between multiple instances of scaled applications. |
cf_instance_internal_ip
|
Internal IP address of the container running the application instance. |
cf_instance_ip
|
External IP address of the host running the application instance. |
The StatsD client Java library populates these dimensions by default. The values are taken from the environment variables that Pivotal Cloud Foundry automatically sets for each running instance. For more information regarding these environment variables, see the official Pivotal documentation.
For more information, see StatsD client Java library.