Geneos ["Geneos"]
["Geneos > Netprobe"]["User Guide"]

Deploy instrumented applications

Overview

This guide takes you through the necessary steps to deploy your instrumented applications in:

  • Kubernetes or OpenShift environment.
  • Pivotal Cloud Foundry 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:

  1. 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:
    • NAMESPACEand POD_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.
  2. 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 default 8125.

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.

  1. 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
    
  2. 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

To deploy a Java application with the StatsD or JVM metrics library:

  1. 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>
  2. Instrument the application using StatsD client Java library. For more information, see StatsD client Java library.
  3. Compile and build the application to produce the JAR file.
  4. 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
    
  5. Log in to the PCF API using the following command (the API host may differ):
    cf login -a api.run.pivotal.io 
    
  6. 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.