register_data_source

For general information on how the Python agent API calls relate to each other, see the API guide.

newrelic.agent.register_data_source(source, application=None, name=None, settings=None, **properties)
Registers a data source for generating custom metric data.

Description

This call registers a data source to be polled at the completion of each harvest cycle for generating custom metric timeslice data. For more about why and how to use data sources for custom metrics, see Custom metric data sources.

In most cases, you won't need to use any optional arguments except for name.

Metrics returned by a data source can be a simple (name, value) tuple where the value is a numeric or float, or the value can be a dictionary that corresponds to an already aggregated data sample for a specific metric.

When returning a dictionary as the metric value, the fields that can be supplied are:

  • count
  • total
  • min
  • max
  • sum_of_squares

For more about these fields and some general usage tips, see Pre-aggregated metrics.

You can also accomplish the same result using agent configuration, which doesn't require you to change your code. To add the data source in this way, add a section in the config file with the prefix data-source:, followed by a unique value to distinguish the section for that of another data source if more than one is specified. Here's an example:

[data-source:memory-usage]
enabled = true
function = samplers:memory_metrics
# application = ...
# name = ...

[data-source:cpu-usage]
enabled = true
function = samplers:CPUMetricsDataSource
# application = ...
# name = ...

If the data source was specified by a function, then the name would be module:function. If a class, then it would be: module:class. The module must be able to be found using the Python module search path.

As with register_data_source, the application to report data to and the name are optional.

Parameters

Parameter Description

source

function or class

Required. The data source, which is a function or class that has had the data_source_generator or data_source_factory decorator assigned.

application

application object

Optional. The application object corresponding to the New Relic-monitored account to report data to. If set to the default of None, the data source will be polled at the end of each harvest cycle for each instrumented app. Alternatively, when an application object is supplied, then the data source will only be polled to generate metrics for that one specific application.

In cases where you need a data source to retain distinct data for each reporting application, you can use a factory pattern to create a separate instance of the data source for each application.

name

string

Optional. The name of the data source. This is used only for logging purposes and will default to the name provided by the data source itself.

settings

string

Optional. The settings to pass to a data source factory.

properties

string

Optional. Any additional properties to pass to the data source factory.

Return value(s)

None.

Example(s)

Registering a data source

Here's an example of some app code that generates custom metric data:

@newrelic.agent.data_source_generator(name='External') 
def services(): 
    # code goes here
    pass


if __name__ == '__main__': 
    application = nr.configure_newrelic() 
    newrelic.agent.register_data_source(services, application)

    while True: 
        pass

Memory usage from data source

import psutil
import os


@newrelic.agent.data_source_generator(name='Memory Usage')
def memory_metrics():
    pid = os.getpid()
    p = psutil.Process(os.getpid())
    m = p.get_memory_info()
    yield ('Custom/Memory/Physical', float(m.rss) / (1024 * 1024))
    yield ('Custom/Memory/Virtual', float(m.vms) / (1024 * 1024))


newrelic.agent.register_data_source(memory_metrics)

For more help

Recommendations for learning more: