Skip to main content

Kubernetes

Motadata APM supports Kubernetes-based application instrumentation using a Kubernetes Operator and OTEL-powered agents. This enables automatic trace collection from containerized workloads running inside a Kubernetes cluster.

Kubernetes instrumentation extends existing Bare Metal and Docker-based APM capabilities to cloud-native environments, enabling multi-language observability across pods and namespaces.

Go to Menu > Settings > APM > Application Registration.

From the Application Registration screen, select the instrumentation type: Kubernetes

Prerequisites​

Before you begin, ensure the following requirements are met:

  • Helm version: 3.9 or higher
  • Kubernetes version: v1.24 or higher
  • Valid SSL certificates (for secure communication)
  • Internet access (for operator deployment)

Supported Languages​

The below are the supported languages while configuring Kubernetes based Application

LanguageVersion
Java8 or Higher
.NET8 and 9
Node18.19.0, 20.6.0 or Higher
Python3.9 or Higher
C++14 or Higher

Instrumentation Configuration​

Step 1: Select Cluster Name​

Choose the Kubernetes cluster where applications are running. If no cluster is available you need to create it by clicking the Add icon.

Once the cluster is selected, the UI dynamically enables the next configuration steps.

Step 2: Apply Certificate Manager​

To enable secure communication between the cluster and Motadata APM:

  • Execute the certificate deployment command displayed under Certificate Manager section.
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

You need to run this command on your main Kubernetes node to install cert-manager, which helps manage security certificates.

Step 3: Deploy Motadata Operator​

Run the operator installation command displayed under the Deploy Motadata Operator.

helm repo add motadata-charts https://motadata2025.github.io/motadata-helm-charts/
helm repo update

      helm upgrade --install motadata-operator motadata-charts/opentelemetry-operator \
  --namespace motadata-operator-np \
  --create-namespace \
  --version 0.99.2 \
  --set manager.image.tag=v0.138.0 \
  --set fullnameOverride=motadata-operator

helm upgrade --install motadata-cr-instrumentation motadata-charts/motadata-cr-instrumentation --set exporter.endpoint=http://172.16.15.218:4318  --set clusterName='k8s.cluster.name={your-cluster}'

helm upgrade --install motadata-apm-agent motadata-charts/motadata-apm-agent \
    --set env.motadataServerUrl="http://172.16.15.218:9433/kubernetes/cluster" --set env.clusterName="{your-cluster}"
info

The {your-cluster} field will be replaced by the cluster name selected by you in the first step.

This command installs the Motadata Operator, Motadata Instrumentation Custom Resources, and Motadata APM Agent in your Kubernetes cluster and enable monitoring and auto-instrumentation.

Step 4: Application Mapping​

After successful operator deployment, the grid of Application Name, Language, and Namespace gets displayed. This action displays detected Kubernetes workloads.

Once the applications are listed, you can use the Search option to find a specific application. You can also use the Namespace filter to narrow down the application list for easier access.

You need to copy the command displayed under the Run below Command section and paste it in the Kubernetes main node to map the application. If you select Application Name associated with C++ Language, then you can follow the below Setup Instructions to map the application.

Setup Instructions​

Setup Instructions

PHASE 1: Environment Setup​

Install the build tools and compile the Motadata Instrumentation C++ SDK inside your container image.

info

This phase adds approximately 15–25 minutes to your first docker build as the C++ SDK is a large codebase being compiled inside the container. Subsequent builds are much faster if you structure your Dockerfile correctly (the SDK build layers are cached by Docker as long as those lines do not change).

1. Verify Your Dockerfile Base Image Has the Required Tools

Open a terminal and run each of these commands inside a container shell, or check your Dockerfile's existing installation block. If any tool is missing, install it using the package manager commands in Step 1a below.

Command to runWhat to expect
cmake --versionMust show version 3.16 or higher. CMake is the build system used to compile the SDK inside the container.
g++ --versionMust show GCC 5 or higher (GCC 7+ recommended). This is the C++ compiler. Alternatively: clang++ --version (Clang 6+).
protoc --versionMust show 3.12 or higher. Protobuf compiler, needed by the Motadata Instrumentation SDK to serialise spans.
curl --versionAny version. libcurl is used to send traces over HTTP from inside the container.
git --versionAny version. Used to clone the SDK source code during docker build.
pkg-config --versionAny version. Helps CMake locate installed libraries inside the container.

Step 1a. Install missing tools

Run the block that matches your base image OS. You can skip tools already present in your image.

Ubuntu / Debian (ubuntu:24.04, debian:bookworm recommended):

# MOTADATA ADD 1: Install instrumentation dependencies
# Add this block directly below your existing apt-get block.
# apt-get safely skips packages that are already installed.
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    pkg-config \
    libcurl4-openssl-dev \
    libssl-dev \
    libprotobuf-dev \
    protobuf-compiler \
    && rm -rf /var/lib/apt/lists/*

RHEL / CentOS / Amazon Linux:

# MOTADATA ADD 1: Install instrumentation dependencies
RUN yum install -y \
    git \
    pkgconfig \
    libcurl-devel \
    openssl-devel \
    protobuf-devel \
    protobuf-compiler \
    gcc-c++ \
    && yum clean all

# On CentOS 7, cmake installs as "cmake3" not "cmake".
# Create an alias: RUN ln -s /usr/bin/cmake3 /usr/bin/cmake
note

All commands return version numbers without errors. Move to Step 2.

2. Clone and Build the Motadata Instrumentation C++ SDK Inside the Container

info

You are adding RUN steps inside your Dockerfile to download and compile the Motadata Instrumentation C++ SDK during docker build. This happens automatically every time the image is built. The SDK is compiled on the container's exact platform, this guarantees compatibility with every Pod. The download is approximately 50 MB and the compilation takes 15–25 minutes. Both steps are cached by Docker and only re-run if these Dockerfile lines change.

Step 2a. Clone the SDK source code

Add this block to your Dockerfile immediately after the MOTADATA ADD 1 dependencies block:

# MOTADATA ADD 2: Clone the Motadata Instrumentation C++ SDK
# --depth 1 downloads only the latest commit, not full history (faster).
# --branch v1.23.0 pins to a known stable release.
# Never use the "main" branch in production, it may have breaking changes.
RUN git clone --depth 1 --branch v1.23.0 \
    https://github.com/open-telemetry/opentelemetry-cpp.git \
    /opt/opentelemetry-cpp \
    && cd /opt/opentelemetry-cpp \
    && git submodule update --init --recursive

Step 2b. Configure and compile the SDK

info

cmake -S reads the CMakeLists.txt and generates Makefiles using the flags below. cmake --build runs the actual compilation using all available CPU cores in parallel. cmake --install copies the compiled headers and .so files to /usr/local inside the container. rm -rf cleans up the source tree to keep image size small.

# MOTADATA ADD 2 (continued): Build and install the SDK
# Configured for HTTP-only export on port 4318. Copy these flags exactly.
RUN cmake -S /opt/opentelemetry-cpp \
    -B /opt/opentelemetry-cpp/build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_STANDARD=14 \
    -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
    -DWITH_OTLP_HTTP=ON \
    -DWITH_OTLP_GRPC=OFF \
    -DBUILD_TESTING=OFF \
    -DWITH_EXAMPLES=OFF \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    && cmake --build /opt/opentelemetry-cpp/build \
    --parallel $(nproc) \
    && cmake --install /opt/opentelemetry-cpp/build \
    && rm -rf /opt/opentelemetry-cpp

# Registers the installed .so files with the OS linker.
# Without this the app crashes at startup with shared library errors.
RUN ldconfig /usr/local/lib
CMake FlagWhat it does and why
-DCMAKE_BUILD_TYPE=ReleaseCompile in Release mode, optimized and smaller binary. Do not use Debug here.
-DCMAKE_CXX_STANDARD=14Use C++14 or higher. The motadata-apm-cpp-instrumentation library supports C++14+.
-DCMAKE_POSITION_INDEPENDENT_CODE=ONRequired for static libraries to link correctly into other programs.
-DWITH_OTLP_HTTP=ONEnable the HTTP exporter, this is how spans are sent to port 4318. Required.
-DWITH_OTLP_GRPC=OFFDisable the gRPC exporter, simpler build, not needed.
-DBUILD_TESTING=OFFDo not compile the SDK test suite. Saves approximately 10 minutes of build time.
-DWITH_EXAMPLES=OFFDo not compile SDK examples. Not needed.
-DCMAKE_INSTALL_PREFIX=/usr/localInstall the compiled SDK headers and libraries to /usr/local a standard system path inside the container.

Step 2c. Verify the installation succeeded (optional, add temporarily during docker build)

# Check that header files were installed
RUN ls /usr/local/include/opentelemetry/
# Expected output: folders named trace/, sdk/, exporters/, common/, etc.

# Check that compiled library files were installed
RUN ls /usr/local/lib/ | grep opentelemetry | head -5
# Expected output: several files named libopentelemetry_*.a
info

The docker build layer completes without errors. The opentelemetry headers and .a library files are present in /usr/local inside the container. Move to Step 3.

note

The most common cause is a missing package in MOTADATA ADD 1. Re-check Step 1a to ensure all tools are present, then repeat Step 2. If protoc --version inside the container shows less than 3.12, install a newer version of protobuf.

3. Clone the Motadata Wrapper into the Container

Add this block to your Dockerfile after your WORKDIR line and before your COPY . . line. The wrapper is cloned relative to WORKDIR as motadata-cpp/ so CMakeLists.txt can reference it using add_subdirectory(motadata-cpp). It must be before COPY so your source files do not overwrite it.

# MOTADATA ADD 3: Clone Motadata wrapper
# Add this block AFTER your WORKDIR and BEFORE your COPY.
# The wrapper is cloned relative to WORKDIR as motadata-cpp/
# so CMakeLists.txt can reference it using add_subdirectory(motadata-cpp).
# Must be BEFORE COPY so your source files do not overwrite it.
RUN git clone --depth 1 \
    https://github.com/motadata2025/motadata-apm-cpp-instrumentation.git \
    motadata-cpp

Your project structure inside the container will look like this:

your-project/                    ← WORKDIR inside container
├── CMakeLists.txt               ← your existing file (you will edit this in Step 4)
├── src/
│   ├── main.cpp
│   └── other_files.cpp
└── motadata-cpp/                ← cloned by MOTADATA ADD 3 above
    ├── include/
    │   └── motadata.h
    ├── src/
    │   └── motadata.cpp
    └── CMakeLists.txt
info

The wrapper is cloned inside the container at the correct location. Move to Phase 2.

If Your Base Image is Not Ubuntu/Debian

This guide was written and tested using ubuntu:24.04. If your application uses a different Linux base image, only the package installation commands in MOTADATA ADD 1 need to change. Everything else, SDK build flags, CMakeLists.txt, code changes, kubectl commands, remains exactly the same.

note

This guide was validated on ubuntu:24.04 with GCC 13 and CMake 3.28. If you use a different base image and encounter issues not listed here, contact your Motadata team for support.

Package Name Equivalents by Distro

Ubuntu / Debian (apt-get)RHEL / CentOS / Amazon Linux (yum/dnf)Alpine (apk)
libcurl4-openssl-devlibcurl-develcurl-dev
libssl-devopenssl-developenssl-dev
libprotobuf-devprotobuf-develprotobuf-dev
protobuf-compilerprotobuf-compilerprotobuf
pkg-configpkgconfigpkgconfig
gitgitgit
g++gcc-c++g++
cmakecmake3cmake

Known Challenges by Distro

DistroChallengeFix
CentOS 7cmake is version 2.x — SDK requires 3.16+yum install cmake3 && ln -s /usr/bin/cmake3 /usr/bin/cmake
CentOS 7GCC is version 4.8 — SDK requires GCC 5+yum install devtoolset-7 && scl enable devtoolset-7 bash or use a newer base image
CentOS 7Protobuf is version 2.x, SDK requires 3.12+Build protobuf from source or use a newer base image such as amazonlinux:2023
RHEL 8 / CentOS 8+cmake package name is cmake not cmake3Use yum install cmake directly
Amazon Linux 2Same cmake and GCC issues as CentOS 7Use amazonlinux:2023 instead, ships with a newer toolchain.
Alpinemusl libc incompatibility with OTel SDKSwitch base image to ubuntu:24.04 or debian:bookworm strongly recommended

Recommended Base Images for Production

Base ImageRecommendationNotes
ubuntu:24.04Strongly recommendedTested and validated. GCC 13, CMake 3.28 out of the box.
debian:bookwormRecommendedSame apt-get packages as Ubuntu. Stable and widely used in production.
amazonlinux:2023SupportedUse dnf instead of yum. Newer toolchain than Amazon Linux 2.
rockylinux:9 / almalinux:9SupportedRHEL 9 compatible. Use dnf. Good alternative to CentOS.
centos:7Not recommendedToo old cmake, GCC, and protobuf all need manual upgrades. Use a newer image.
alpineNot recommendedmusl libc causes OTel SDK build issues. Switch to ubuntu:24.04.

PHASE 2: Project Integration​

Add the motadata-apm-cpp-instrumentation library to your C++ project.

4. Update CMakeLists.txt

info

You need to add exactly two things to your existing CMakeLists.txt:

  1. add_subdirectory(motadata-cpp) this tells CMake to build the library
  2. motadata curl pthread this in your target_link_libraries

That is all. Two additions. Nothing else changes.

Here is what your CMakeLists.txt should look like after the changes. Lines marked with # ADD indicate additions required for instrumentation:

cmake_minimum_required(VERSION 3.16)
project(YourAppName)

set(CMAKE_CXX_STANDARD 17)

find_package(Threads REQUIRED)

# ADD — includes motadata-cpp as part of your build
# motadata-cpp/ is cloned inside the project by Dockerfile (Step 3 ADD 3)
add_subdirectory(motadata-cpp)

add_executable(YourApp main.cpp)

target_include_directories(YourApp PRIVATE
    ${CMAKE_SOURCE_DIR}
    motadata-cpp/include        # ADD — exposes motadata.h to your source files
)

target_link_libraries(YourApp PRIVATE
    Threads::Threads
    motadata                    # ADD — links libmotadata.a (wrapper static library)
    curl                        # ADD — required by wrapper for HTTP trace export
    pthread                     # ADD — required threading library for batch processor
    # ... your existing libraries stay here unchanged ...
)
AdditionWhy it is needed
add_subdirectory(motadata-cpp)Tells CMake to enter the motadata-cpp/ folder and process its CMakeLists.txt. This automatically builds the library as part of your project build. No separate build step needed.
motadataLinks the compiled wrapper library into your application. After this, your code can call motadata:: functions.
curlLinks libcurl — the HTTP client library. The wrapper uses curl internally to POST spans to the Collector. This is a system library already installed in your image.
pthreadLinks POSIX threads library. Required on Linux for multi-threaded code. Standard system library.

5. Verify the Library Compiles

Before writing any instrumentation code, confirm the library builds correctly inside the container. Run docker build to trigger the full compile:

docker build -t your-app:1.0.0 .

In the cmake output during docker build you should see a line like:

-- motadata configuration:
--   Version      : 1.0.0
--   C++ Standard : 17
Library integrated successfully

The docker build completes with no errors. Move to Phase 3 to add instrumentation to your code.

Error: Could not find opentelemetry-cpp

The SDK was not installed correctly in Phase 1. Confirm the cmake --install line is present in your Dockerfile and that /usr/local/include/opentelemetry/ exists inside the container before trying again.

Linker error: undefined reference to curl_easy_init

Add curl to target_link_libraries in your CMakeLists.txt. Rebuild the image.

Linker error: undefined reference to pthread_create

Add pthread to target_link_libraries in your CMakeLists.txt. Rebuild the image.

Verification​

Once the Application is Running:

  • Confirm that the service has been registered successfully.
  • On the service registration screen, the service trace collection Status should display "Running."
  • The traces will start appearing in the APM Explorer screen.