Upgrade savant-rs to 0.4 (#881)

* #870 update savant-rs to 0.4.1

* #870 update telemetry sample

* #870 add TLS support in telemetry

* #870 update template

* #870 update jaeger docker image

* #870 configure TLS in telemetry sample

* #870 fix Jaeger with TLS sample

.gitignore

@@ -64,3 +64,6 @@ data
 
 # logs (perf measurement)
 logs
+
+# certificates
+certs

docs/source/advanced_topics/0_dead_stream_eviction.rst

@@ -22,6 +22,6 @@ Take a look at the ``default.yml`` for details:
 
 .. literalinclude:: ../../../savant/config/default.yml
   :language: YAML
-  :lines: 188-221
+  :lines: 195-228
 
 You can override only required parameters in your module YAML configuration file. Also, take a look at corresponding environment variables helping to configure the parameters without specifying them in the module config.

docs/source/advanced_topics/10_client_sdk.rst

@@ -61,13 +61,35 @@ Sources ingest frames and their metadata to a running module.
 .. code-block:: python
 
     import time
-    from savant_rs import init_jaeger_tracer
+    from savant_rs import telemetry
+    from savant_rs.telemetry import (
+        ContextPropagationFormat,
+        Protocol,
+        TelemetryConfiguration,
+        TracerConfiguration,
+    )
     from savant_rs.primitives import VideoFrameBatch, VideoFrameContent
     from savant.client import JaegerLogProvider, JpegSource, SourceBuilder
 
     # Initialize Jaeger tracer to send metrics and logs to Jaeger.
     # Note: the Jaeger tracer also should be configured in the module.
-    init_jaeger_tracer('savant-client', 'localhost:6831')
+    telemetry_config = TelemetryConfiguration(
+        context_propagation_format=ContextPropagationFormat.Jaeger,
+        tracer=TracerConfiguration(
+            service_name='savant-client',
+            protocol=Protocol.Grpc,
+            endpoint='http://jaeger:4317',
+            # tls=ClientTlsConfig(
+            #     certificate='/path/to/ca.crt',
+            #     identity=Identity(
+            #         certificate='/path/to/client.crt',
+            #         key='/path/to/client.key',
+            #     ),
+            # ),
+            # timeout=5000,  # milliseconds
+        ),
+    )
+    telemetry.init(telemetry_config)
 
     # Build the source
     source = (
@@ -96,6 +118,8 @@ Sources ingest frames and their metadata to a running module.
     time.sleep(1)  # Wait for the module to process the batch
     result.logs().pretty_print()
 
+    # Shutdown the Jaeger tracer
+    telemetry.shutdown()
 
 Sink Example
 ^^^^^^^^^^^^
@@ -124,4 +148,4 @@ Sinks retrieve results from a module.
 
 
 
-.. youtube:: -oTwsN6Cpxs
+.. youtube:: -oTwsN6Cpxs

docs/source/advanced_topics/9_open_telemetry.rst

@@ -58,26 +58,33 @@ Use ``params.telemetry.tracing`` to configure OpenTelemetry for the module.
           provider: jaeger
           provider_params:
             service_name: demo-pipeline
-            endpoint: jaeger:6831
+            # Available protocols: grpc, http_binary, http_json.
+            # Protocol should be compatible with the port in endpoint.
+            # See https://www.jaegertracing.io/docs/1.62/deployment/#collector
+            protocol: grpc
+            endpoint: "http://jaeger:4317"
+            timeout: 5000 # milliseconds
+            tls:
+              certificate: /path/to/ca.crt
+              identity:
+                  certificate: /path/to/client.crt
+                  key: /path/to/client.key
 
 .. note::
 
-    The module `template <https://github.com/insight-platform/Savant/tree/develop/samples/template>`_ already has valid configuration, considering that the Jaeger is launched in the all-in-one mode recommended on the Jaeger `website <https://www.jaegertracing.io/docs/1.48/getting-started/>`_:
+    The module `template <https://github.com/insight-platform/Savant/tree/develop/samples/template>`_ already has valid configuration, considering that the Jaeger is launched in the all-in-one mode recommended on the Jaeger `website <https://www.jaegertracing.io/docs/1.62/getting-started/>`_:
 
     .. code-block:: bash
 
         docker run -d --name jaeger \
           -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
-          -p 6831:6831/udp \
-          -p 6832:6832/udp \
-          -p 5778:5778 \
           -p 16686:16686 \
           -p 4317:4317 \
           -p 4318:4318 \
           -p 14250:14250 \
           -p 14268:14268 \
           -p 14269:14269 \
           -p 9411:9411 \
-          jaegertracing/all-in-one:1.48
+          jaegertracing/all-in-one:1.62.0
 
 .. youtube:: DkNifuKg-kY

docs/source/reference/api/client.rst

@@ -15,12 +15,33 @@ Source usage example:
 .. code-block:: python
 
     import time
-    from savant_rs import init_jaeger_tracer
+    from savant_rs.telemetry import (
+        ContextPropagationFormat,
+        Protocol,
+        TelemetryConfiguration,
+        TracerConfiguration,
+    )
     from savant.client import JaegerLogProvider, JpegSource, SourceBuilder
 
     # Initialize Jaeger tracer to send metrics and logs to Jaeger.
     # Note: the Jaeger tracer also should be configured in the module.
-    init_jaeger_tracer('savant-client', 'localhost:6831')
+    telemetry_config = TelemetryConfiguration(
+        context_propagation_format=ContextPropagationFormat.Jaeger,
+        tracer=TracerConfiguration(
+            service_name='savant-client',
+            protocol=Protocol.Grpc,
+            endpoint='http://jaeger:4317',
+            # tls=ClientTlsConfig(
+            #     certificate='/path/to/ca.crt',
+            #     identity=Identity(
+            #         certificate='/path/to/client.crt',
+            #         key='/path/to/client.key',
+            #     ),
+            # ),
+            # timeout=5000,  # milliseconds
+        ),
+    )
+    telemetry.init(telemetry_config)
 
     # Build the source
     source = (
@@ -38,6 +59,9 @@ Source usage example:
     time.sleep(1)  # Wait for the module to process the frame
     result.logs().pretty_print()
 
+    # Shutdown the Jaeger tracer
+    telemetry.shutdown()
+
 Sink usage example:
 
 .. code-block:: python
@@ -65,7 +89,12 @@ Async example (both source and sink):
 .. code-block:: python
 
     import asyncio
-    from savant_rs import init_jaeger_tracer
+    from savant_rs.telemetry import (
+        ContextPropagationFormat,
+        Protocol,
+        TelemetryConfiguration,
+        TracerConfiguration,
+    )
     from savant.client import JaegerLogProvider, JpegSource, SinkBuilder, SourceBuilder
 
 
@@ -102,9 +131,29 @@ Async example (both source and sink):
     async def main():
         # Initialize Jaeger tracer to send metrics and logs to Jaeger.
         # Note: the Jaeger tracer also should be configured in the module.
-        init_jaeger_tracer('savant-client', 'localhost:6831')
+        telemetry_config = TelemetryConfiguration(
+            context_propagation_format=ContextPropagationFormat.Jaeger,
+            tracer=TracerConfiguration(
+                service_name='savant-client',
+                protocol=Protocol.Grpc,
+                endpoint='http://jaeger:4317',
+                # tls=ClientTlsConfig(
+                #     certificate='/path/to/ca.crt',
+                #     identity=Identity(
+                #         certificate='/path/to/client.crt',
+                #         key='/path/to/client.key',
+                #     ),
+                # ),
+                # timeout=5000,  # milliseconds
+            ),
+        )
+        telemetry.init(telemetry_config)
+
         await asyncio.gather(run_sink(), run_source())
 
+        # Shutdown the Jaeger tracer
+        telemetry.shutdown()
+
 
     asyncio.run(main())
 

docs/source/savant_101/12_module_definition.rst

@@ -54,7 +54,7 @@ The following parameters are defined for a Savant module by default:
 
 .. literalinclude:: ../../../savant/config/default.yml
   :language: YAML
-  :lines: 1-188
+  :lines: 1-195
 
 .. note::
 
@@ -210,7 +210,14 @@ Example:
         provider: jaeger
         provider_params:
           service_name: demo-pipeline
-          endpoint: jaeger:6831
+          protocol: grpc
+          endpoint: "http://jaeger:4317"
+          timeout: 5000 # milliseconds
+          tls:
+            certificate: /path/to/ca.crt
+            identity:
+                certificate: /path/to/client.crt
+                key: /path/to/client.key
 
 Read more on OpenTelemetry in :doc:`/advanced_topics/9_open_telemetry`.
 

docs/source/savant_101/12_pipeline.rst

@@ -17,7 +17,7 @@ Default module configuration file already defines the :py:attr:`~savant.config.s
 
 .. literalinclude:: ../../../savant/config/default.yml
   :language: YAML
-  :lines: 188-
+  :lines: 195-
 
 It is possible to redefine them, but the encouraged operation mode assumes the use of ZeroMQ source and sink.
 

samples/telemetry/README.md

@@ -1,6 +1,6 @@
 # OpenTelemetry Example
 
-A simple pipeline demonstrating the use of OpenTelemetry in Savant. The pipeline contains one element, [Blur PyFunc](blur.py). It applies gaussian blur to the frame and contains OpenTelemetry instrumenting code. OpenTelemetry instrumenting is initialized with environment variables: see compose files for details. The telemetry is collected by the all-in-one Jaeger [container](https://www.jaegertracing.io/docs/1.48/getting-started/#all-in-one). The container also includes the Jaeger UI.
+A simple pipeline demonstrating the use of OpenTelemetry in Savant. The pipeline contains one element, [Blur PyFunc](blur.py). It applies gaussian blur to the frame and contains OpenTelemetry instrumenting code. OpenTelemetry instrumenting is initialized with environment variables: see compose files for details. The telemetry is collected by the all-in-one Jaeger [container](https://www.jaegertracing.io/docs/1.62/getting-started/#all-in-one). The container also includes the Jaeger UI.
 
 Below are a few screenshots from the Jaeger UI.
 
@@ -63,3 +63,83 @@ docker compose -f samples/telemetry/docker-compose.l4t.yml up
 
 # Ctrl+C to stop running the compose bundle
 ```
+
+## Running Jaeger with TLS
+
+Jaeger and Savant support TLS for telemetry collection. [docker-compose-with-tls.x86.yml](docker-compose-with-tls.x86.yml) and [docker-compose-with-tls.l4t.yml](docker-compose-with-tls.l4t.yml) compose files demonstrate how to run Jaeger with TLS enabled (for both Jaeger and Savant authentication).
+
+### Generate Certificates
+
+Create directory for certificates:
+
+```bash
+mkdir samples/telemetry/certs
+```
+
+Generate CA:
+
+```bash
+openssl genpkey -algorithm RSA -out samples/telemetry/certs/ca.key
+openssl req -new -x509 -days 365 \
+    -key samples/telemetry/certs/ca.key \
+    -out samples/telemetry/certs/ca.crt \
+    -subj "/CN=jaeger-ca"
+```
+
+Generate server key and certificate:
+
+```bash
+openssl genpkey -algorithm RSA -out samples/telemetry/certs/server.key
+openssl req -new \
+    -key samples/telemetry/certs/server.key \
+    -out samples/telemetry/certs/server.csr \
+    -subj "/CN=jaeger"
+openssl x509 -req -days 365 \
+    -in samples/telemetry/certs/server.csr \
+    -CA samples/telemetry/certs/ca.crt \
+    -CAkey samples/telemetry/certs/ca.key \
+    -CAcreateserial \
+    -out samples/telemetry/certs/server.crt \
+    -extfile <(echo "subjectAltName=DNS:jaeger")
+```
+
+Make the server key readable by the container:
+
+```bash
+chmod +r samples/telemetry/certs/server.key
+```
+
+Generate client key and certificate:
+
+```bash
+openssl genpkey -algorithm RSA -out samples/telemetry/certs/client.key
+openssl req -new \
+    -key samples/telemetry/certs/client.key \
+    -out samples/telemetry/certs/client.csr \
+    -subj "/CN=module"
+openssl x509 -req -days 365 \
+    -in samples/telemetry/certs/client.csr \
+    -CA samples/telemetry/certs/ca.crt \
+    -CAkey samples/telemetry/certs/ca.key \
+    -CAcreateserial \
+    -out samples/telemetry/certs/client.crt
+```
+
+### Run Demo with TLS
+
+```bash
+# you are expected to be in Savant/ directory
+
+# if x86
+docker compose -f samples/telemetry/docker-compose-with-tls.x86.yml up
+
+# if Jetson
+docker compose -f samples/telemetry/docker-compose-with-tls.l4t.yml up
+
+# open 'rtsp://127.0.0.1:554/stream/0' in your player
+# or visit 'http://127.0.0.1:888/stream/0/' (LL-HLS)
+
+# navigate to 'http://localhost:16686' to access the Jaeger UI
+
+# Ctrl+C to stop running the compose bundle
+```