register_data_source (Python agent API)

Syntax

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.

Tip

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.

Tip

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 values

None.

Examples

Memory usage from data source

import newrelic.agent
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.memory_info()
    yield ('Custom/Memory/Physical', float(m.rss) / (1024 * 1024))
    yield ('Custom/Memory/Virtual', float(m.vms) / (1024 * 1024))


@newrelic.agent.background_task()
def main():
    # Example code, business as usual
    print("Hello, world!")


if __name__ == "__main__":
    newrelic.agent.initialize(config_file="newrelic.ini")
    app = newrelic.agent.register_application()
    newrelic.agent.register_data_source(memory_metrics, app)
    
    main()