{"id":1658,"date":"2024-11-20T07:37:31","date_gmt":"2024-11-20T07:37:31","guid":{"rendered":"https:\/\/marketaylor.synology.me\/?p=1658"},"modified":"2024-11-20T20:01:43","modified_gmt":"2024-11-20T20:01:43","slug":"otel-context-propagation-cpp","status":"publish","type":"post","link":"https:\/\/marketaylor.synology.me\/?p=1658","title":{"rendered":"OTel Context Propagation for MQ Applications: part 2 – C\/C++"},"content":{"rendered":"\n

The first article<\/a> in this series introduced OpenTelemetry (OTel) tracing with IBM MQ. It showed how the trace context can flow when the application is using the MQ Node.JS or Go interfaces. This article carries on the story for OTel context propagation, this time talking about C++ and C applications.<\/p>\n\n\n\n\n\n\n\n

Instrumenting C and C++ applications<\/h2>\n\n\n\n

Just as with the other language interfaces, your application should already have OTel instrumentation. With C and C++ applications, that is not as straightforward as some other environments. <\/p>\n\n\n\n

For a start, the OTel project does not provide pre-built libraries, though there are some places you might be able to download them from, depending on your operating system version. As another aspect, there are no automatic or standard library integrations. So you will probably have to build the OTel libraries for yourself, and then add the necessary instrumentation to the application directly.<\/p>\n\n\n\n

OTel also do not provide any native C support; everything is done via C++. So instrumenting C applications will likely require some wrapper layer to convert C to the object-oriented APIs. That’s how this API Exit is written – using a mixture of languages to convert MQ’s C interfaces to the C++ operations driving the OTel API. (The fact that this made it easier to use constructs such as Maps was certainly a benefit but it wasn’t the primary purpose.)<\/p>\n\n\n\n

The MQ language binding and exit<\/h2>\n\n\n\n

While the Node.js and Go propagation layer sits above the C MQI, manipulating message properties and the MQRFH2 structures, the C variant runs underneath the C MQI. It is implemented as an API Exit<\/a>. But it is logically doing an identical thing to those other bindings. Your application does not need to do anything different, beyond its own OTel work. Calls to the MQI are transparently picked up and processed.<\/p>\n\n\n\n

Outbound messages have properties added that can be picked up by a receiving application; inbound messages with context have that context linked into any existing OTel trace\/spans. This exit does not emit any new traces or spans of its own.<\/p>\n\n\n\n

This layer may be running inside a Go or Node.js program, but there is no “double accounting”. The wrappers’ OTel work takes precedence if the apps are instrumented.<\/p>\n\n\n\n

The exit<\/a> has been written and tested on Linux platforms only. It MIGHT work on AIX with small tweaks to the Makefile (though getting the OTel SDK libraries might be more challenging); it would require more changes to build and run on Windows. It can work in conjunction with, but does not require, the Instana MQ Tracing exit.<\/p>\n\n\n\n

An incidental benefit of this exit is that it demonstrates many of the features of a larger API Exit. In particular, how you can work with message properties<\/a>.<\/p>\n\n\n\n

RemoveRFH2 Option?<\/h5>\n\n\n\n

One difference from the other MQ OTel binding layers is that there is no RemoveRFH2<\/code> option on the MQPMO and MQGMO structures. So your application might receive “unexpected” properties or RFH2 header blocks. Part of the reason for not implementing that feature in this exit is because the MQI cannot be extended in any way: the API Exit is inside the MQI calls, not wrapping it. The application would need to use an alternative mechanism. Perhaps an environment variable, but I don’t like using those for this kind of feature. If it turns out to be necessary, then it could be added in future.<\/p>\n\n\n\n

Building the exit<\/h2>\n\n\n\n

First, you need to get a copy of the MQ API exit. Use git clone<\/code> to pull down a copy from here<\/a>. The OTel exit is in the apix\/otel<\/code> subdirectory. Before building the exit itself, you also need the OTel cpp libraries.<\/p>\n\n\n\n

OpenTelemetry library dependency<\/h4>\n\n\n\n

The exits depend on having the opentelemetry cpp libraries already available. Either archive or shared libraries can be used depending on your preference. But using shared libraries is more likely to need additional configuration such as LD_LIBRARY_PATH<\/code> to be set so that they can be found and loaded at runtime.<\/p>\n\n\n\n

While you might be able to find existing pre-built libraries, it’s more likely that you will have to build them yourself. See Getting Started material here<\/a> for information on creating these libraries. For this exit, you do not need any of the exporters to be built, which means that many of the dependencies (eg grpc) are not necessary.<\/p>\n\n\n\n

However you do need to build the OTel libraries with the ABI version 2 option. This is done by setting -DWITH_ABI_VERSION_2=ON -DWITH_ABI_VERSION_1=OFF<\/code> in the cmake<\/em> configuration. You also need -DCMAKE_POSITION_INDEPENDENT_CODE=ON<\/code>.<\/p>\n\n\n\n

This is where I might like to have a rant about how inappropriate C++ is for library packages \u2026 But I’ll mostly resist that temptation.<\/p>\n\n\n\n

The API Exit<\/h4>\n\n\n\n

Once you are in the correct subdirectory of the MQ Exits repository, execute the Makefile with make<\/code>! The output from that step contains two things:<\/p>\n\n\n\n