GitHub - RuntimeTools/SwiftMetrics: Swift Application Metrics instruments the Sw...
source link: https://github.com/RuntimeTools/SwiftMetrics
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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):
- The current working directory.
- The
.build/checkouts/SwiftMetrics.git--<id>
directory (orPackages/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 settingLD_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 version2.5.1
- Fix compilation warnings2.5.0
- Removal of SwiftyRequest
and support for Kitura-NIO2.4.2
- Removal of Swift 4.2 compiler warnings2.4.1
- Refactoring to remove SwiftyJSON dependency and minor fixes2.4.0
- New REST interface2.3.0
- Support Swift 4.12.2.1
- Minor dependency version change2.2.0
- New summary tab in SwiftMetrics dashboard2.1.0
- Remove KituraRequest dependency and switch to SwiftyRequest2.0.4
- Reapply Swift-cfenv version change2.0.3
- Provide crash fix without Swift-cfenv version change2.0.2
- Fix crash when deployed to IBM cloud.2.0.1
- Minor fixes.2.0.0
- Dependency update to use Kitura 21.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.
Recommend
-
33
README.md SwiftMetrics A Metrics API package for Swift. Almost all production server software needs to emit metrics information for observabilit...
-
5
Metrics Capturing JVM- and application-level metrics. So you know what's going on. For more information...
-
2
Home Server-Side Swift Tutorials...
-
96
iOS-Performance-Optimization - 关于iOS 性能优化梳理、内存泄露、卡顿、网络、GPU、电量、 App 包体积瘦身、启动速度优化等、Instruments 高级技巧、常见的优化技能- Get — Edit
-
64
接收到用户反馈,我们的App耗电量大,从问题看,只能猜测到 CPU 开销比较大或者地理位置获取时候比较耗电。我们一起去敲敲轮子,哪里需要修补下。
-
51
“The Razer Phone 2 will (highly likely) finally have Chroma LED effects built in. They're working to use an LED controller from Texas Instruments to make this happen so the phone lights up when notifications come in.”
-
50
README.md DeallocationChecker Learn about leaking view controllers without opening Instruments. Usage First, enable the library by call...
-
49
-
79
-
30
iOS developers have plenty of logging solutions. Apple provides some, whereas others are by third-party frameworks. However, there’s a relatively new logging solution on the block that leaves the rest in the dust: Apple’...
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK