Application Metrics for Swift

Application Metrics for Swift instruments the Swift runtime for performance monitoring, providing the monitoring data programatically via an API or visually with its built-in dashboard.

Application Metrics for Swift provides the following built-in data collection sources:

Source	Description
Environment	Machine and runtime environment information
CPU	Process and system CPU
Memory	Process and system memory usage
Latency	Dispatch Queue latency

SwiftMetricsKitura adds the additional collection source:

Source	Description
HTTP	HTTP metric information

Getting Started

Prerequisites

The Application Metrics for Swift agent supports the following runtime environments:

• Swift v4.2 GA on:
  • 64-bit runtime on Linux (Ubuntu 14.04, 16.04)
  • 64-bit runtime on macOS (x64)
• Swift v4.1 GA on:
  • 64-bit runtime on Linux (Ubuntu 14.04, 16.04)
  • 64-bit runtime on macOS (x64)
• Swift v4 GA on:
  • 64-bit runtime on Linux (Ubuntu 14.04, 16.04)
  • 64-bit runtime on macOS (x64)
• Swift v3.1.1 GA using SwiftMetrics version 1.2.5 on:
  • 64-bit runtime on Linux (Ubuntu 14.04, 15.10)
  • 64-bit runtime on macOS (x64)

Installation

Application Metrics for Swift can be installed by adding a dependency into your Package.swift file and updating your targets to include SwiftMetrics as a dependency:

   dependencies: [
      .package(url: "https://github.com/RuntimeTools/SwiftMetrics.git", from: "2.4.0")
   ]
   ...
   targets: [
      .target(name: "MyApp", dependencies: ["SwiftMetrics"], path: "Sources")]

Swift Package manager will automatically clone the code required and build it during compilation of your program:

• Linux: swift build
• macOS: swift build -Xlinker -lc++

Configuring Application Metrics for Swift

Once Application Metrics for Swift is added as a dependency to your Swift application, you should find a configuration file inside the .build folder, .build/checkouts/SwiftMetrics.git--<id>/swiftmetrics.properties (or the Packages directory for older versions of Swift, Packages/SwiftMetrics-<version>/swiftmetrics.properties). This is used to configure connection options, logging and data source options.

Application Metrics for Swift will attempt to load swiftmetrics.properties from one of the following locations (in order):

1. The current working directory.
2. The .build/checkouts/SwiftMetrics.git--<id> directory (or Packages/SwiftMetrics-<version> for older versions of Swift).

Please note that the default configuration has minimal logging enabled.

Running Application Metrics for Swift

Modifying your application

To load SwiftMetrics and get the base monitoring API, add the following to the start-up code for your application:

import SwiftMetrics

let sm = try SwiftMetrics()
let monitoring = sm.monitor()

If you would like to monitor Kitura HTTP data as well, then use the following instead:

import SwiftMetrics
import SwiftMetricsKitura

let sm = try SwiftMetrics()
SwiftMetricsKitura(swiftMetricsInstance: sm)
let monitoring = sm.monitor()

Application Metrics for Swift Dashboard

To use the built in dashboard, you add the following code to your application

import SwiftMetrics
import SwiftMetricsDash

// Enable SwiftMetrics Monitoring
let sm = try SwiftMetrics()   

// Pass SwiftMetrics to the dashboard for visualising
let smd = try SwiftMetricsDash(swiftMetricsInstance : sm)  

By default, SwiftMetricsDash will start its own Kitura server and serve the page up under http://<hostname>:<port>/swiftmetrics-dash

The port being used is logged to the console when your application starts:

• SwiftMetricsDash : Starting on port 8080

Prometheus Support

To use SwiftMetrics to provide a Prometheus endpoint, you add the following code to your application

import SwiftMetrics
import SwiftMetricsPrometheus

// Enable SwiftMetrics Monitoring
let sm = try SwiftMetrics()   

// Pass SwiftMetrics to SwiftMetricsPrometheus
let smp = try SwiftMetricsPrometheus(swiftMetricsInstance : sm)

By default, SwiftMetricsPrometheus will provide the Prometheus endpoint under http://<hostname>:<port>/metrics

The port being used is logged to the console when your application starts:

• SwiftMetricsPrometheus : Starting on port 8080

Application Metrics for Swift Agent

SwiftMetrics() returns the Application Metrics for Swift Agent - this runs parallel to your code and receives and emits data about your application to any connected clients. The sm.monitor() call returns a Application Metrics for Swift Local Client, connected to the Agent sm over a local connection.

You can then use the monitoring object to register callbacks and request information about the application:

monitoring.on({ (env: InitData) in
   for (key, value) in env {
      print("\(key): \(value)\n")
   }
})

func processCPU(cpu: CPUData) {
   print("\nThis is a custom CPU event response.\n cpu.timeOfSample = \(cpu.timeOfSample),\n cpu.percentUsedByApplication = \(cpu.percentUsedByApplication),\n cpu.percentUsedBySystem = \(cpu.percentUsedBySystem).\n")
}

monitoring.on(processCPU)

In order to monitor your own custom data, you need to implement a struct that implements the base SwiftMetrics data protocol, SMData. This has no required fields so you can put in just the data you're interested in.

private struct SnoozeData: SMData {
   let cycleCount: Int
}

private func snoozeMessage(data: SnoozeData) {
   print("\nAlarm has been ignored for \(data.cycleCount) seconds!\n")
}

monitoring.on(snoozeMessage)

sm.emitData(SnoozeData(cycleCount: 40))

//prints "Alarm has been ignored for 40 seconds!"

API Documentation

SwiftMetrics.start()

Starts the Application Metrics for Swift Agent. If the agent is already running this function does nothing.

SwiftMetrics.stop()

Stops the Application Metrics for Swift Agent. If the agent is not running this function does nothing.

SwiftMetrics.setPluginSearch(toDirectory: URL)

Sets the directory that Application Metrics for Swift will look in for data source / connector plugins.

SwiftMetrics.monitor() -> SwiftMonitor

Creates a Application Metrics for Swift Local Client instance, connected to the Application Metrics for Swift Agent specified by 'SwiftMetrics'. This can subsequently be used to get environment data and subscribe to data generated by the Agent.. This function will start the Application Metrics for Swift Agent if it is not already running.

SwiftMetrics.emitData<T: SMData( _: T)

Allows you to emit custom Data specifying the type of Data as a string. Data to pass into the event must implement the SMData protocol.

SwiftMonitor.getEnvironmentData() -> [ String : String ]

Requests a Dictionary object containing all of the available environment information for the running application. If called before the 'initialized' event has been emitted, this will contain either incomplete data or no data.

SwiftMonitor.on<T: SMData>((T) -> ())

If you supply a closure that takes either a pre-supplied API struct or your own custom struct that implements the SMData protocol, and returns nothing, then that closure will run when the data in question is emitted.

SwiftMetricsKitura(swiftMetricsInstance: SwiftMetrics) (when importing SwiftMetricsKitura)

Creates a SwiftMetricsKitura instance, which will monitor Kitura HTTP metrics and emit them via the SwiftMetrics instance specified.

SwiftMetricsBluemix(swiftMetricsInstance: SwiftMetrics) (when importing SwiftMetricsBluemix)

Creates a SwiftMetricsBluemix instance, which will send metrics to the Auto Scale service

API Data Structures

All of the following structures implement the SMData protocol to identify them as available to be used by SwiftMetrics.

public protocol SMData {
}

CPU data structure

Emitted when a CPU monitoring sample is taken.

• public struct CPUData: SMData
  • timeOfSample (Int) the system time in milliseconds since epoch when the sample was taken.
  • percentUsedByApplication (Float) the percentage of CPU used by the Swift application itself. This is a value between 0.0 and 1.0.
  • percentUsedBySystem (Float) the percentage of CPU used by the system as a whole. This is a value between 0.0 and 1.0.

Memory data structure

Emitted when a memory monitoring sample is taken.

• public struct MemData: SMData
  • timeOfSample (Int) the system time in milliseconds since epoch when the sample was taken.
  • totalRAMOnSystem (Int) the total amount of RAM available on the system in bytes.
  • totalRAMUsed (Int) the total amount of RAM in use on the system in bytes.
  • totalRAMFree (Int) the total amount of free RAM available on the system in bytes.
  • applicationAddressSpaceSize (Int) the memory address space used by the Swift application in bytes.
  • applicationPrivateSize (Int) the amount of memory used by the Swift application that cannot be shared with other processes, in bytes.
  • applicationRAMUsed (Int) the amount of RAM used by the Swift application in bytes.

HTTP data structure (when including SwiftMetricsKitura)

Emitted when an HTTP monitoring sample is taken.

• public struct HTTPData: SMData
  • timeOfRequest (Int) the system time in milliseconds since epoch when the request was made.
  • url (String) the request url.
  • duration (Double) the duration in milliseconds that the request took.
  • statusCode (HTTPStatusCode) the HTTP status code of the request.
  • requestMethod (String) the method {GET SET} of the request.

Initialized data structure

Emitted when all expected environment samples have been received, signalling a complete set of environment variables is available for SwiftMonitor.getEnvironmentData().

• public struct InitData: SMData
  • data ([String: String] Dictionary) of environment variable name:value pairs. The contents vary depending on system.

Environment data structure

Emitted when an environment sample is taken. The Dictionary obtained with this data may not represent the complete set of environment variables.

• public struct EnvData: SMData
  • data ([String: String] Dictionary) of environment variable name:value pairs. The contents vary depending on system.

Latency data structure

Emitted when a Latency sample is taken.

• public struct LatencyData: SMData
  • timeOfSample (Int) the system time in milliseconds since epoch when the sample was taken.
  • duration (Double) the duration the sample waited in the dispatch queue to be executed.

Samples

There are two samples available:

• commonSample demonstrates how to get data from the common data types, using the API.
• emitSample demonstrates the use of Custom Data emission and collection.

To use either, navigate to their directory and issue swift build (on macOS, swift build -Xlinker -lc++)

Troubleshooting

Find below some possible problem scenarios and corresponding diagnostic steps. Updates to troubleshooting information will be made available on the SwiftMetrics wiki: Troubleshooting. If these resources do not help you resolve the issue, you can open an issue on the Application Metrics for Swift issue tracker.

Checking Application Metrics for Swift has started

By default, a message similar to the following will be written to console output when Application Metrics for Swift starts:

[Fri Aug 21 09:36:58 2015] com.ibm.diagnostics.healthcenter.loader INFO: Swift Application Metrics 1.0.1-201508210934 (Agent Core 3.0.5.201508210934)

Error "Failed to open library .../libagentcore.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.15' not found"

This error indicates there was a problem while loading the native part of the module or one of its dependent libraries. libagentcore.so depends on a particular (minimum) version of the C runtime library and if it cannot be found this error is the result.

Check:

• Your system has the required version of libstdc++ installed. You may need to install or update a package in your package manager. If your OS does not supply a package at this version, you may have to install standalone software - consult the documentation or support forums for your OS.
• If you have an appropriate version of libstdc++installed, ensure it is on the system library path, or use a method (such as setting LD_LIBRARY_PATH environment variable on Linux) to add the library to the search path.

Source code

The source code for Application Metrics for Swift is available in the Swiftmetrics project. Information on working with the source code -- installing from source, developing, contributing -- is available on the SwiftMetrics wiki.

License

This project is released under an Apache 2.0 open source license.

Versioning scheme

This project uses a semver-parsable X.0.Z version number for releases, where X is incremented for breaking changes to the public API described in this document and Z is incremented for bug fixes and for non-breaking changes to the public API that provide new function.

Development versions

Non-release versions of this project (for example on github.com/RuntimeTools/SwiftMetrics) will use semver-parsable X.0.Z-dev.B version numbers, where X.0.Z is the last release with Z incremented and B is an integer. For further information on the development process go to the SwiftMetrics wiki: Developing.

Version

2.6.0

Release History

2.6.0 - Update to latest graphMetrics version
2.5.1 - Fix compilation warnings
2.5.0 - Removal of SwiftyRequest and support for Kitura-NIO
2.4.2 - Removal of Swift 4.2 compiler warnings
2.4.1 - Refactoring to remove SwiftyJSON dependency and minor fixes
2.4.0 - New REST interface
2.3.0 - Support Swift 4.1
2.2.1 - Minor dependency version change
2.2.0 - New summary tab in SwiftMetrics dashboard
2.1.0 - Remove KituraRequest dependency and switch to SwiftyRequest
2.0.4 - Reapply Swift-cfenv version change
2.0.3 - Provide crash fix without Swift-cfenv version change
2.0.2 - Fix crash when deployed to IBM cloud.
2.0.1 - Minor fixes.
2.0.0 - Dependency update to use Kitura 2
1.2.5 - Minor fixes.
1.2.4 - Prometheus support, memory graph checkboxes, URL filtering & drop Swift 3.0 support.
1.2.3 - Dependency updates, graph resizing and Swift 4 support.
1.2.2 - Minor fixes.
1.2.1 - Minor fixes.
1.2.0 - Improvements to testing.
1.1.0 - Add WSS support.
1.0.3 - Swift 3.1.1 support (including dashboard).
1.0.2 - Initial Swift 3.1 support (SwiftMetricsDash not working on 3.1).
1.0.0 - First GA release.
0.0.12 - BlueMix AutoScaling support.
0.0.11 - BlueMix support.
0.0.10 - Addition of Kitura HTTP collection source.
0.0.9 - Initial development release.