=======
Filters
=======

Markus lets you write and use filters to modify generated metrics.

.. versionadded:: 2.0.0

.. contents::
   :local:


Using filters
=============

Filters can be configured to run on a :py:class:`markus.main.MetricsInterface`
instance that you build with ``get_metrics()``.

For example, say you had a Python module and all metrics published from code
in that module should get the additional tag ``source:foomodule``. Then you
could do something like this::

    import markus
    from markus.filters import AddTagFilter

    metrics = markus.get_metrics(__name__, filters=[AddTagFilter("source:cache")])

    class CacheInterface:
        def get(self, key, default=None):
            with metrics.timing("cache.get"):
                # do stuff


The ``cache.get`` metric will have ``source:cache`` as a tag.

You can also specify filters on backends when configuring markus. For example,
say you want to add a ``hostid:HOSTID`` tag to all metrics being published to
the Datadog backend. You could do this::

    import os

    import markus
    from markus.filters import AddTagFilter

    HOSTID = os.environ.get("HOSTID", "none")

    markus.configure(
        backends=[
            {
                "class": "markus.backends.datadog.DatadogMetrics",
                "options": {
                    "statsd_host": "example.com",
                    "statsd_port": 8125,
                    "statsd_namespace": ""
                },
                "filters": [AddTagFilter("host:%s" % HOSTID)]
            }
        ]
    )

All metrics generated will have the ``hostid`` tag.

Filters can be used to drop metrics, too. Say you want metrics with
``debug:true`` spit out to the logging backend, but not the Datadog backend.
You could do this::

    import os

    import markus
    from markus.main import MetricsFilter

    class DropDebugFilter(MetricsFilter):
        def filter(self, record):
            if "debug:true" in record.tags:
                return
            return record

    markus.configure(
        backends=[
            {
                "class": "markus.backends.datadog.DatadogMetrics",
                "options": {
                    "statsd_host": "example.com",
                    "statsd_port": 8125,
                    "statsd_namespace": ""
                },
                "filters": [DropDebugFilter()]
            },
            {
                # Log metrics to the logs
                'class': 'markus.backends.logging.LoggingMetrics',
            },
        ]
    )

Metrics generated with ``debug:true`` will show up in the logs, but not get
sent to the Datadog backend.


Writing filters
===============

Filters subclass the :py:class:`markus.main.MetricsFilter` class.

All filters need to implement the ``.filter()`` method. The ``filter`` method
takes :py:class:`markus.main.MetricsRecord` instance and either:

1. returns the record,
2. changes the record in place and returns the record,
3. returns ``None`` signifying the record should be dropped

This filter adds a host id tag to all outgoing metrics::

    import os

    from markus.main import MetricsFilter

    class HostFilter(MetricsFilter):
        def __init__(self):
            self.hostid_tag = "hostid:%s" % os.environ.get("HOSTID")

        def filter(self, record):
            record.tags.append(self.hostid_tag)
            return record

Filters can also drop metrics. This one drops any metric that has a
"debug:true" tag::

    from markus.main import

    class DebugFilter(MetricsFilter):
        def filter(self, record):
            if "debug:true" in record.tags:
                return
            return record


.. autoclass:: markus.main.MetricsFilter


Included filters
================

Markus includes one filter for the common case of adding tags to all metrics
generated by a metrics interface.

.. autoclass:: markus.filters.AddTagFilter