otelanalyzer 1.0.1

Pure C lib for python3 (or C if u wanna) to analyze traces check for compliance with the OpenTelemetry standard

Pure C lib for python3 (or C if u wanna) to analyze traces and check for compliance with the OpenTelemetry standard.

Example:

from otelanalyzer import *
import json

def testTrace(a: Analyzer, t: str):
    tr = Trace()
    tr.traceString = t
    tr.traceId = "1" * 32
    tr.serviceName = "some-name"
    a.analyze_btrace(tr)
    r = a.get_counters('some-name')
    print(json.dumps(r, indent=4))

if __name__ == '__main__':
    t = "[{'spanId': '0000000000000000', 'serviceName': 'some-name', 'traceId': '00000000000000000000000000000000', 'project': 'some-project', 'service': 'some-service'}]"
    a = Analyzer()
    testTrace(a, t)

Result

$ python3 test_lib.py
{
    "UndefTraceStatus": 0,
    "myMissingParent": 0,
    "notmyMissingParent": 0,
    "myNoParentInTrace": 0,
    "notmyNoParentInTrace": 0,
    "myDuplicateSpan": 0,
    "notmyDuplicateSpan": 0,
    "myBadSpanIdSize": 0,
    "notmyBadSpanIdSize": 0,
    "myBadTraceIdSize": 0,
    "notmyBadTraceIdSize": 0,
    "myExamples": [],
    "notmyExamples": [],
    "badTraceCount": 0,
    "mySpanCount": 1,
    "traceCount": 1
}

$ valgrind --tool=memcheck --leak-check=full python3 test_lib.py

==374573== HEAP SUMMARY:

==374573==     in use at exit: 397,058 bytes in 11 blocks
==374573==   total heap usage: 3,462 allocs, 3,451 frees, 4,881,009 bytes allocated
==374573==
==374573== LEAK SUMMARY:
==374573==    definitely lost: 0 bytes in 0 blocks
==374573==    indirectly lost: 0 bytes in 0 blocks
==374573==      possibly lost: 0 bytes in 0 blocks
==374573==    still reachable: 397,058 bytes in 11 blocks
==374573==         suppressed: 0 bytes in 0 blocks

Plugins

Plugins for this package can add more robust trace analysis and edge case management. They will be called after splitting traces into spans, so you can work more comfortably. The motivation for this feature is to be able to add NDA-protected features without forking the project.

They are called during traceString analyzation. Steps are as follows:

1. Split traceString into spans, add span statuses, and increase error counters accordingly
2. Call all plugins
3. Free the trace object for optimization reasons

C plugins

You can add your C analysis plugins in the src/plugin_manager.c file. Their source files should be placed in the src/plugins/ folder. A plugin should have a function with Analyzer* and Trace* parameters and should return void. There is an example plugin in src/plugins/example_plugin.*

You are strongly encouraged to write your plugins with header files, as demonstrated in example_plugin.

Your function will be called after parsing the trace into separate spans. Please keep in mind that trace.traceString will be freed at this point for optimization reasons.

Python plugins

You can add your own Python plugin to modify the existing behavior of the analyzer. To do this, create a function that takes dict[str, Counter] and Trace as input parameters. Then, pass a pointer (just the function's name without brackets or parameters) to Analyzer.plg_manager.add_plugin(your_func). Plugins will be executed in a first-in, first-out order.

Your function's behaviour is not restricted in any way except for input-output types: feel free to call your custom classes, write raw data right into DB and whatever.

dict[str, Counter] contains service names as keys and their corresponding ErrorCounter values. Only services that appear at least once in the trace spans are included.

Trace is the current trace object being analyzed. See the plugin execution steps for reference.

IF YOU WANT TO MODIFY the Counter value corresponding to your service, YOU MUST return the updated dict[str, Counter] object. Keep in mind that the Trace object is read-only, so your changes will not be applied directly.

If you want to modify the examples property of a counter, YOU MUST also update ExamplesCount, or your changes will not take effect.

Plugin example:

def example_plugin(d: dict[str, Counter], t: Trace):
    d["some-name"].mySpanCount = 9999999
    d["some-name"].myBadTraceExamples.append("pipa")
    d["some-name"].myExamplesCount += 1
    return d

def test_plugin(a: Analyzer, t: str):
    a.plg_manager.add_plugin(lambda_func)

Installation

$ pip install otelanalyzer

or

$ python3 setup.py build_ext --inplace && mv ./otelanalyzer.so ./otelanalyzer

Dependencies

The package has no dependencies.

Planned features

• Python unit tests
• Wheels for Python 3.13 (you can already build it locally, check installation)