Skip to content

Metrics

Deep offers the ability to dynamically create metrics at arbitrary points in the code. This allows you to create metrics about specific actions within your applications without having to change the code.

To attach a metric a 'Metric' must be attached to the tracepoint config.

{
  "path": "some/file.py",
  "line_number": 22,
  "metrics": [
    {
      "name": "session_created",
      "labelExpressions": [
        {
          "key": "user_id",
          "value": {
            "expression": "user.id"
          }
        }
      ]
    }
  ]
}

metric{path="some/file.py" line=22 name="session_created" label_user_id="{user.id}"}

The above example would create a metric called session_created with the labels user_ud: 167252 (the value of the label evaluated at runtime). The value of the labels can be either expressions (as above) or static values. The value of the metric is optional, if not set then the value will be 1, if set the value should be a valid expression for the point it is executed.

Supported providers

The specific supported providers is dependent on the client that is being used. In all cases custom providers can be set using the plugin architecture of the client. As a generalisation the following providers will be detected and used automatically:

  • Prometheus
  • OpenTelemetry (OTel)

For more info on what providers are supported by which clients see the client docs.

Example (User Session Duration)

Let us imagine a scenario where we want to track when a user session is destroyed. Let us imagine the follow code is called when a user session is destroyed.

users/session.py
22
23
24
25
def delete_session(self, user, session):
    self.process_session_end(session)
    session = self.db.delete_session(user.id)
    return True

In this example we can create the tracepoint as follows:

{
  "path": "users/sessions.py",
  "line_number": 24,
  "metrics": [
    {
      "name": "session_duration",
      "type": "HISTOGRAM",
      "labelExpressions": [
        {
          "key": "user_id",
          "value": {
            "expression": "user.id"
          }
        }
      ],
      "expression": "time.time() - session.start_ts"
    }
  ]
}

This tracepoint would result in the Deep intercepting line 24 and creating a new histogram metric using the value of the expression time.time() - session.start_ts as the value. This metric will then be pushed to metric provider and captured by your existing metric services (e.g. Prometheus).

Languages specifics

As Deep supports a variety of languages the way the expressions need to be defined depends on the language. There are also some caveats depending on the language being used.

Warning

In all cases it is possible to execute code that is potentially harmful to your application. It is therefore the responsibility of the user to ensure the expressions will not have an adverse effect on the application.

Python

Python will evaluate the expressions using eval this allows you to execute any valid python code within the expressions. This allows for a lot of power to collect data, however it also allows for some potential bad scenarios. Where potentially harmful code can be executed. As a result we have tried to defend the user from some scenarios.

  • Global values are not exposed to eval

Java

In Java there is no equivalent of eval this means that to execute code we need to provide an evaluator. The default evaluator is the 'Nashorn' JavaScript engine. This was chosen as it is shipped in the JDK, so we can reduce the size of the Deep agent. However, this evaluator is not available in all version of Java and as such it is possible that expressions will not work in when using Java.

Note

It is planned to release additional evaluators that can be used when Nashorn is not available.

ColdFusion (Adobe/Lucee)

In ColdFusion expression will use the Evaluate function (or evaluate for Lucee) that is available on the page context. This allows for ColdFusion expressions to be evaluated.