Documentation

• What is Nodetime?
• Features
  • Transaction Tracing
    • Sample Filtering
    • Custom Tracing
  • Metrics
    • Historical Metrics
    • Custom Metrics
  • Database Monitoring
  • CPU Profiling
  • Memory Profiling
  • Alerts
  • Team Features
• Subscription Plans
• Installation and Use
• Troubleshooting
• Runtime Overhead
• Agent API
  • Methods
• Metrics API

 

 

What is Nodetime?

Nodetime is an application performance monitoring and analytics service - an all-round solution for monitoring, profiling and tracing Node.js application performance problems down to the root cause.

Nodetime reveals response time and other internals of HTTP requests and underlying HTTP, database, file system and other API calls in your Node.js application. Coupled with related process and OS state information, real-time and historical metrics, and monitoring as well as CPU and memory profiling it enables tracing performance problems down to the root cause. Nodetime supports multiple APIs including native HTTP client, file system, cluster, Socket.io, Redis, MongoDB, MySQL, PostgreSQL, Memcached and Cassandra. HTTP-based data stores like CouchDB and Riak are supported via HTTP API.

The profiler running within the application securely sends profiling data to the Nodetime server, which forwards it to a browser in real-time.

Nodetime is a high-level profiler designed to run in production environments. By hooking up to various APIs it gives developers clear API-level visibility of performance, i.e. time and CPU usage, averages, stack traces and much more.

Features

Transaction Tracing

A core feature of Nodetime, which gives you visibility of what's happening inside your application by showing requests and operations, e.g. API calls, with a lot of information, including response time, CPU time, operations such as database calls, http client requests, file system and other API calls which happened at the same time. This all completed with related context information and application state.

Sample Filtering

If there are too many requests or operations handled by the application, Nodetime will send only the slowest samples of requests and their operations to the profiler web console (though still emitting all samples on the local API level). For systems under load, this can result in making the faster but more important requests invisible. Filtering allows you to specify what exactly you want to see. For example, you can specify to sample only those requests, which are slower than 100ms or match a certain URL pattern. Or, requests which have an underlying database call to a database on a specific machine with a given IP address. While API gives you the full power of programmatic filtering, profiling web console at nodetime.com makes it a few clicks to filter samples down to very specific ones.

Check out the screencast to see sample filtering in action.

Custom Tracing

Nodetime samples requests and some Socket.io communication out of the box. For other types of applications or a specific operation tracing need it provides simple API functions and extension mechanisms. Using time() and timeEnd() (see agen's API documentation) functions will tell a lot about the enclosed code execution. Read more in the blog post A Powerful Alternative to Node's console.time()

Metrics

The Nodetime agent sends different types of metrics to the server. The metrics include OS Load average and free memory, Node's RSS and Heap size as well as average response / CPU times, error rates and counts for HTTP client / server requests and supported API calls and libraries, e.g. Socket.io, File System, Redis, MongoDB, MySQL, PostgreSQL, Memcached and Cassandra. These metrics are then viewable in web console in as real-time metrics and as historical metrics.

Historical Metrics

Historical metrics are not shown for particular process, but are presented in an averaged process view. So if, for example, two physical machines are running ten instances of node process each, e.g. using node cluster, historical metrics will present values averaged from these twenty processes. The default metric retention is one year. Metric charts are viewable in intervals of 1 hour, 12 hours, 2 days, 1 week, 1 month, or 1 year.

Custom Metrics

Using metric API call, custom metrics can be sent to the Nodetime server and presented in the same way as the automatic metrics. Please refer to agent's API documentation.

Database Monitoring

Monitor databases used by your applications without any extra setup. Database status metrics will be available along with others to watch, analyze and trigger alerts. Currently Redis and MongoDB are supported. Read more in the blog post Redis and MongoDB Server Monitoring.

CPU Profiling

As a logical next step after detecting high CPU utilization, Nodetime makes it incredibly easy to use V8's built-in sampling CPU profiler to analyze hot spots and locate inefficient functions. Read more about using the CPU profiler in the blog post CPU Profiling with Nodetime.

Memory Profiling

Nodetime's memory profiling feature uses V8's built-in heap profiler, which allows to take heap snapshots. The snapshots are then analyzed by Nodetime and presented in a form, which leads to faster memory leak detection. Read more about memory profiling in the blog post Detecting Memory Leaks in Node.js Applications.

Alerts

It is important to be notified when an application is experiencing performance problems in order to prevent downtime and be able to quickly locate the problem's root cause, while profiling exact problem symptoms, which might disappear later. Nodetime allows users to create threshold and anomaly alerts for many internal metrics of the application - for example, if HTTP response time is continuously high or there are too few requests. It is also possible to set alerts on API call metrics of different supported libraries, such as MongoDB, Redis, and MySQL.

An alert is not immediately sent when it is higher or lower than the specified threshold. To make sure that the alert condition persists, several values are tested in a short period of time.

Team Features

Applications can be shared between accounts. Simple but powerful feature, application sharing enables team collaboration and centralized billing for Nodetime accounts.

Subscription Plans

Nodetime offers both free and paid subscription plans. All plans have the same feature set and functionally. The difference between the plans is the number of agents per account allowed to simultaneously send data to Nodetime, where agent is the nodetime module running within a Node process. Number of agents normally corresponds to the number of processes used. For example a single cluster may start several processes on one server. The number of agents will be equal to the number of processes forked by the cluster. On PaaS such as Heroku the number of processes can be dynamically changed from administration console.

Nodetime also allows grouping processes into applications by using appName configuration variable. The number applications is not relevant for choosing the right subscription plan, contrary to the overall number of processes running under one account, i.e. using the same account key.

Check out subscription plan pricing on the pricing page.

Please contact our Support Team if you are not sure what is the best plan for your application(s).

Installation and Use

Install Nodetime with npm

npm install nodetime

Installation of nodetime may produce an error if an optional dependency of nodetime package cannot be compiled. This error can be ignored for Node versions since 0.8 (0.6 for linux) as the agent will fallback to precompiled versions of the native extentions, shipped with the agent. To test if the precompiled version was successfully loaded in case of compilation error, temporary add debug:true flag to the profile() call (see below) and watch the logs.

The following call should be placed before any other require statement in your application, e.g. at the first line of your main module

require('nodetime').profile({
    accountKey: 'your_account_key', 
    appName: 'your_application_name'
});

Several applications can be associated with one account.

Sign up now and try it out!

Troubleshooting

Installation produces compilation error

Installation of nodetime may produce an error if an optional dependency of nodetime package cannot be compiled. This error can be ignored for Node versions since 0.8 (0.6 for linux) as the agent will fallback to precompiled versions of the native extentions, shipped with the agent. To test if the precompiled version was successfully loaded in case of compilation error, temporary add debug:true flag to the profile() call and watch the logs.

Web console link is not printed

Link-based profiling is no longer supported. Please register an account and use account key in the profile() call.

I don't see any requests and operations in the web console

Use debug:true flag to check if there are errors. If no errors are reported by the agent, one possible reason is that the number of processes or applications is exceeding the limits for the account.

CPU and heap profiler do not return any result

This might mean that an optional native dependency of the nodetime package was not installed correctly. Use debug:true flag to find out the reason.

You can contact our support team for all technical questions.

Run-time Overhead

Nodetime is based on probes hooked into API calls and callbacks using wrappers. It measures time, adds variables and creates objects, which naturally causes overhead. A significant part of the overhead is the reading of stack traces of sampled operations taking a couple of hundred microseconds, but which is limited to 1000 stack traces per perocess run to make sure lowest possible overhead for systems under load. Although, the probes are mostly attached around calls involving network communication, which makes the overhead insignificant. However, it is recommended to measure overhead for specific cases, for example in case of too many library calls or high CPU usage.

Agent API

require('nodetime') - returns a singleton instance of Nodetime object.

Methods:

profile(options) - Starts the profiler. Options are:

• accountKey - Only for registered users. Account key can be found on Account Information page.
• appName - Only for registered users. Optional. Application name defines the scope of one logical application. If omitted, will default to "Default Application".
• debug - Used for debugging nodetime itself, so hopefully you won't need it.
• stdout - If true, dumps samples using console.log().
• proxy - An HTTP proxy to be used for connecting to the Nodetime sever.
• namedTransactions - contains hash of name and URL pattern pairs for tracing particular transactions identified by the given URL pattern. Read more about this feature in the blog post Tracing Transactions with URL Patterns.
• features - Disable/enable (false/true) the following features:
  • transactionProfiler - Disable/enable request and operation profiling. Default: true.
  • hostMetrics - Disabe/enable host specific metrics. Should not be enabled in applications, which do not run on identifiable hosts, e.g. clouds, PaaS, etc. Default: false.
  • redisMetrics - Disable/enable Redis monitoring. Default: true.
  • mongodbMetrics - Disable/enable MongoDB monitoring. Deafult: true.

expressErrorHandler() - If exress error handler is used, add after app.use(app.router) to make agent's HTTP probe aware of caught exceptions.

pause() - Pauses the transaction profiler.

resume([seconds]) - Activates the transaction profiler for a given duration. If no seconds argument is specified, defaults to 180 seconds. Applies only to transaction profiler. The agent will still be sending metrics and slowest transaction samples.

destroy() - Destroys the agent from sending data by cleaning up all the internal timers and event listeners.Useful for graceful shutdown of processes.

time(scope, name[, context]) - Marks time measurement start and returns promise object. Optional context parameter is used to pass more information about the execution context as hash pairs.

promise.end([context]) - Marks time measurement end. At this point a sample containing measured interval information, such as response time, CPU time, nested operations and related data will be sent to the server to be shown in the Transaction Profiler, if active, and optionally in historically slowest transactions. Optional context parameter is used to pass more information about execution context as hash pairs. If Error field is specified, the sample will also show up in Errors section of Transaction Profiler and error rates. Additionally, call metrics are automatically generated, e.g. response time, count per minute and error rate.

metric(scope, name, value, unit, op) - aggregates and sends metrics to the web console every minute. The argumets are:

• scope - The namespace of the metric, e.g., 'Visitor Statistics', 'A/B Testing', etc. Required.
• name - The name of the metric, e.g., 'Visits per Minute', etc. Required.
• unit - Measurment unit, e.g. 'KB', 'ms', etc. Optional.
• op - The aggregation operation of the metric. Required. Can take the following values:
  • avg - Will calculate the average of all values in one minute.
  • sum - Will calculate the sum of all values in one minute. The value is averaged on the server if received from multiple processes within one minute.
  • inc - Will calculate the sum of all values in one minute. The value is summed up on the server if received from multiple processes within one minute.
  • set - (formerly gauge) Will always overwrite the value of the metric and will send the latest value to the server. The same logic will be applied on the server if receiving this metric from multiple processes.

Metrics API

Metrics API offers a simple way to send metrics to Nodetime as well as list metrics and request time series values. Unlike other Metrics services, Nodetime's Metric API is designed for continuos measurements. Sending data to Nodetime at irregular intervals will introduce gaps in time series charts and may cause some algorithms to overlook the metric.

Metric Aggregation

The following aggregation operations are available:

• Average (avg) - all values submitted during one aggregation minute are averaged.
• Increment (inc) - all values submitted during one aggregation minute are summed up.
• Set (set) - only one value submitted during one aggregation minute is taken as that minutes's value, overwriting previous values, if any.

Best Practices

• To avoid gaps in time series charts, send each metric at least once per minute.
• If you're going to send many metrics per minute, it is recommended to aggregate the values on the server and send aggregated metric only once per minute.
• For submitting rate metrics, e.g. response times, from different processes, avg aggregation operation can be used to make sure the end metric reflects the data from all submitters.

Authentication

Authentication is done using account key, which can be found on Account Settings page. There are two ways to send authentication information:

• sending the key in account_key URL parameter
• sending the key in X-Account-Key header
• basic auth with account key in the username

Creating and Updating Metrics

POST https://metrics-api.nodetime.com/api/v1/metrics/add - creates or updates metric(s). Requires JSON formatted array of metrics in post data.

Parameters:

• app_name - name of the application, to which the metric should be assigned to. Application should exist. Required.
• scope - metric namespace. Required.
• name - metric name. Required.
• value - metric value. Number. Required.
• unit - measurement unit, e.g. ms, KB, etc. Can take any string value. Optional.
• op - metric aggregation operation. Can be avg and set. See Metric Aggregation section for details. Required.

Note: if multiple metrics are sent in one batch, the app_name should be the same for all metrics.

Example:

curl  \
   -H 'X-Account-Key: 93c659932063a542ca4c7a0970d5872d74d9d580' \
   -H 'Content-Type: application/json' \
   -d '[{ 
         "app_name": "Nodetime Demo", 
         "scope": "Scam Detection", 
         "name": "Number of logins", 
         "value": 12, 
         "unit": "count", 
         "op": "avg" 
      }]' \
   -X POST \
   https://metrics-api.nodetime.com/api/v1/metrics/add

Listing Metrics

GET https://metrics-api.nodetime.com/api/v1/metrics/list - lists metrics

Example:

curl \
  -H 'X-Account-Key: 93c659932063a542ca4c7a0970d5872d74d9d580' \
  -X GET \ 
  https://metrics-api.nodetime.com/api/v1/metrics/list 

Metric Time Series

GET https://metrics-api.nodetime.com/api/v1/metrics/series/:id

Parameters:

• id - metric id. Metric ids are returned by the list endpoint.
• minutes - the interval for which to return the values.

Example:

curl \
  -H 'X-Account-Key: 93c659932063a542ca4c7a0970d5872d74d9d580' \
  -X GET \ 
  https://metrics-api.nodetime.com/api/v1/metrics/series/84de625db71b56d480d47bdc32377d23144b8c65?minutes=15