(instrumenting-flow)=

Instrumentation

A {class}~jina.Flow exposes configuration parameters for leveraging OpenTelemetry Tracing and Metrics observability features. These tools let you instrument and collect various signals which help to analyze your application's real-time behavior.

A {class}~jina.Flow is composed of several Pods, namely the {class}~jina.serve.runtimes.gateway.GatewayRuntime, {class}~jina.Executors, and potentially a {class}~jina.serve.runtimes.head.HeadRuntime (see the {ref}architecture overview <architecture-overview>). Each Pod is its own microservice. These services expose their own metrics using the Python OpenTelemetry API and SDK.

Tracing and Metrics can be enabled and configured independently to allow more flexibility in the data collection and visualization setup.

:class: seealso
Refer to {ref}`OpenTelemetry Setup <opentelemetry>` for a full detail on the OpenTelemetry data collection and visualization setup.

Prometheus-only based metrics collection will soon be deprecated. Refer to {ref}`Prometheus/Grafana Support <monitoring>` section for the deprecated setup.

Tracing

```python
from jina import Flow

f = Flow(
    tracing=True,
    traces_exporter_host='http://localhost',
    traces_exporter_port=4317,
).add(uses='jinaai://jina-ai/SimpleIndexer')

with f:
    f.block()
```

In `flow.yaml`:
```yaml
jtype: Flow
with:
  tracing: true
  tracing_exporter_host: 'localhost'
  tracing_exporter_port: 4317
executors:
- uses: jinaai://jina-ai/SimpleIndexer
```

```bash
jina flow --uses flow.yaml
```

This Flow creates two Pods: one for the Gateway, and one for the SimpleIndexer Executor. The Flow propagates the Tracing configuration to each Pod so you don't need to duplicate the arguments on each Executor.

The traces_exporter_host and traces_exporter_port arguments configure the traces exporter which are responsible for pushing collected data to the collector backend.

:class: seealso
Refer to {ref}`OpenTelemetry Setup <opentelemetry>` for more details on exporter and collector setup and usage.

Available Traces

Each Pod supports different default traces out of the box, and also lets you define your own custom traces in the Executor. The Runtime name is used to create the OpenTelemetry Service Resource attribute. The default value for the name argument is the Runtime or Executor class name.

Because not all Pods have the same role, they expose different kinds of traces:

Gateway Pods

Head Pods

Executor Pods

Beyond the above-mentioned default traces, you can define {ref}`custom traces <instrumenting-executor>` for your Executor. 

Metrics

Prometheus-only based metrics collection will soon be deprecated. Refer to {ref}`Prometheus/Grafana Support <monitoring>` section for the deprecated setup.

```python
from jina import Flow

f = Flow(
    metrics=True,
    metrics_exporter_host='http://localhost',
    metrics_exporter_port=4317,
).add(uses='jinaai://jina-ai/SimpleIndexer')

with f:
    f.block()
```

In `flow.yaml`:
```yaml
jtype: Flow
with:
  metrics: true
  metrics_exporter_host: 'localhost'
  metrics_exporter_port: 4317
executors:
- uses: jinaai://jina-ai/SimpleIndexer
```

```bash
jina flow --uses flow.yaml
```

The Flow propagates the Metrics configuration to each Pod. The metrics_exporter_host and metrics_exporter_port arguments configure the metrics exporter responsible for pushing collected data to the collector backend.

:class: seealso
Refer to {ref}`OpenTelemetry Setup <opentelemetry>` for more details on the exporter and collector setup and usage.

Available metrics

Each Pod supports different default metrics out of the box, also letting you define your own custom metrics in the Executor. All metrics add the Runtime name to the metric attributes which can be used to filter data from different Pods.

Because not all Pods have the same role, they expose different kinds of metrics:

Gateway Pods

You can find more information on the different type of metrics in Prometheus [here](https://prometheus.io/docs/concepts/metric_types/#metric-types)

Head Pods

Executor Pods

The Executor also adds the Executor class name and the request endpoint for the @requests or @monitor decorated method level metrics:

Beyond the default metrics outlined above, you can also define {ref}`custom metrics <instrumenting-executor>` for your Executor. 

`jina_process_request_seconds` and `jina_receiving_request_seconds` are different:
 
 -  `jina_process_request_seconds` only tracks time spent calling the function.
 - `jina_receiving_request_seconds` tracks time spent calling the function **and** the gRPC communication overhead.

See also

• {ref}Defining custom traces and metrics in an Executor <instrumenting-executor>
• {ref}How to deploy and use OpenTelemetry in Jina-serve <opentelemetry>
• Tracing in OpenTelemetry
• Metrics in OpenTelemetry