SpitfireYük Testi ve APMYenilikler

C++ servisini OTel ile bağlamak

C++'ta ajan yok: servise bir header ve birkaç satır ekler, opentelemetry-cpp'yi derlemeye katar ve yeniden derlersiniz. Servisin istekleri bundan sonra Spitfire'a trace olarak gider (gelen traceparent'ı sürdüren server span'leri). Bu rehber yalnız trace gönderir; ortam dosyasındaki LOGS ve METRICS satırları servis ileride log ya da metrik gönderirse diye kalır.

Gerekenler: CMakeLists.txt'li kaynak kod, derleme makinesinde vcpkg (ya da Conan) ve genel sayfadaki değerler.

İpucu

APM → Servisler → Servisler → Servis ekle sihirbazı bu adımları sizin değerlerinizle doldurur; her adım kopyalayıp yapıştıracağınız tek komut olur. Sihirbazla bağlayın.

Sürüm tablosu

C++ Paket Not
C++14 ve sonrası, CMake 3.16+ otlp-http özelliğiyle opentelemetry-cpp 1.30.0 (vcpkg); 1.26.0 (Conan Center) OTLP HTTP exporter'ı curl ve protobuf çeker; vcpkg ve Conan bunları da derler
C++11 ve öncesi desteklenmiyor opentelemetry-cpp C++14 ister

Sürümünüz: CMakeLists.txt'teki CMAKE_CXX_STANDARD (ya da -std= bayrağı). Örnek cpp-httplib için; başka bir HTTP sunucusunda (Boost.Beast, Drogon, Crow) handler aynı şekilde yazılır: StartServerSpan'e isteğin bir başlığını döndüren fonksiyonu ve route kalıbını verin.

Doğrulandı: 2026-11-10. Kaynak: OTLP HTTP örneği, OTLP exporter ortam değişkenleri, vcpkg port'u, Conan Center.

Linux (systemd)

  1. src/otel.h dosyasını oluşturun, şunu yapıştırın:
cpp
// OpenTelemetry for the service: traces over OTLP HTTP (opentelemetry-cpp).
// IS_OTEL_ENABLED=true turns it on; any other value leaves it off. Addresses,
// tokens, sampling and the service name come from the OTEL_* environment values.
#pragma once

#include <cstdlib>
#include <map>
#include <memory>
#include <string>
#include <utility>

#include "opentelemetry/context/propagation/global_propagator.h"
#include "opentelemetry/context/propagation/text_map_propagator.h"
#include "opentelemetry/context/runtime_context.h"
#include "opentelemetry/exporters/otlp/otlp_http_exporter_factory.h"
#include "opentelemetry/exporters/otlp/otlp_http_exporter_options.h"
#include "opentelemetry/sdk/resource/resource.h"
#include "opentelemetry/sdk/trace/batch_span_processor_factory.h"
#include "opentelemetry/sdk/trace/batch_span_processor_options.h"
#include "opentelemetry/sdk/trace/provider.h"
#include "opentelemetry/sdk/trace/samplers/parent_factory.h"
#include "opentelemetry/sdk/trace/samplers/trace_id_ratio_factory.h"
#include "opentelemetry/sdk/trace/tracer_provider.h"
#include "opentelemetry/sdk/trace/tracer_provider_factory.h"
#include "opentelemetry/trace/propagation/http_trace_context.h"
#include "opentelemetry/trace/provider.h"

namespace otel {

namespace api = opentelemetry::trace;
namespace sdk = opentelemetry::sdk::trace;
namespace prop = opentelemetry::context::propagation;
namespace nostd = opentelemetry::nostd;

inline std::string Env(const char *name, const char *def) {
  const char *v = std::getenv(name);
  return v && *v ? v : def;
}

inline std::shared_ptr<sdk::TracerProvider> &Provider() {
  static std::shared_ptr<sdk::TracerProvider> p;
  return p;
}

// Call first in main.
inline void Setup() {
  if (Env("IS_OTEL_ENABLED", "") != "true") return;
  // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, _HEADERS and _CERTIFICATE are read here
  opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
  auto processor = sdk::BatchSpanProcessorFactory::Create(
      opentelemetry::exporter::otlp::OtlpHttpExporterFactory::Create(opts), sdk::BatchSpanProcessorOptions{});
  // service.name; OTEL_RESOURCE_ATTRIBUTES (version, environment) is added by Create
  auto resource = opentelemetry::sdk::resource::Resource::Create(
      {{"service.name", Env("OTEL_SERVICE_NAME", "<service-name>")}});
  // parentbased_traceidratio: a caller's decision is kept, new traces by OTEL_TRACES_SAMPLER_ARG
  std::shared_ptr<sdk::Sampler> ratio =
      sdk::TraceIdRatioBasedSamplerFactory::Create(std::strtod(Env("OTEL_TRACES_SAMPLER_ARG", "1").c_str(), nullptr));
  Provider() = sdk::TracerProviderFactory::Create(std::move(processor), resource, sdk::ParentBasedSamplerFactory::Create(ratio));
  std::shared_ptr<api::TracerProvider> global = Provider();
  sdk::Provider::SetTracerProvider(global);
  prop::GlobalTextMapPropagator::SetGlobalPropagator(
      nostd::shared_ptr<prop::TextMapPropagator>(new api::propagation::HttpTraceContext()));
}

// Call before main returns: sends the spans that are left.
inline void Shutdown() {
  if (Provider()) {
    Provider()->ForceFlush();
    Provider()->Shutdown();
  }
}

inline nostd::shared_ptr<api::Tracer> Tracer() {
  return api::Provider::GetTracerProvider()->GetTracer("otel");
}

// The request's headers as the propagator reads them; get(name) returns a header ("" when absent).
template <class Fn>
class Headers : public prop::TextMapCarrier {
 public:
  explicit Headers(Fn get) : get_(std::move(get)) {}
  nostd::string_view Get(nostd::string_view key) const noexcept override {
    auto &v = seen_[std::string(key.data(), key.size())];
    v = get_(std::string(key.data(), key.size()));
    return v;
  }
  void Set(nostd::string_view, nostd::string_view) noexcept override {}

 private:
  Fn get_;
  mutable std::map<std::string, std::string> seen_;
};

// A server span for a request, continuing an incoming traceparent (Spitfire's test).
// route is the route pattern ("/items/:id"), so spans group by route, not by path.
template <class Fn>
nostd::shared_ptr<api::Span> StartServerSpan(const std::string &method, const std::string &route, Fn get) {
  Headers<Fn> headers(std::move(get));
  auto current = opentelemetry::context::RuntimeContext::GetCurrent();
  auto parent = prop::GlobalTextMapPropagator::GetGlobalPropagator()->Extract(headers, current);
  api::StartSpanOptions o;
  o.kind = api::SpanKind::kServer;
  o.parent = parent;
  return Tracer()->StartSpan(method + " " + route, {{"http.request.method", method}, {"http.route", route}}, o);
}

// Ends a server span with the response status (5xx marks it as an error).
inline void EndServerSpan(const nostd::shared_ptr<api::Span> &span, int status) {
  span->SetAttribute("http.response.status_code", status);
  if (status >= 500) span->SetStatus(api::StatusCode::kError);
  span->End();
}

}  // namespace otel
  1. main'in olduğu dosyada (örneğin src/main.cpp) header'ı ekleyin, önce Setup'ı, main dönmeden önce Shutdown'ı çağırın ve her istek handler'ında bir server span açın:
cpp
#include "otel.h"

int main() {
  otel::Setup();  // first in main
  httplib::Server svr;
  svr.Get("/items/:id", [](const httplib::Request &req, httplib::Response &res) {
    auto span = otel::StartServerSpan(req.method, "/items/:id", [&](const std::string &h) { return req.get_header_value(h); });
    auto scope = otel::Tracer()->WithActiveSpan(span);
    res.set_content("item " + req.path_params.at("id"), "text/plain");
    otel::EndServerSpan(span, 200);
  });
  svr.listen("0.0.0.0", 8080);
  otel::Shutdown();  // before main returns: sends the spans that are left
}
  1. Paketi vcpkg ile kurun (Windows'ta da aynı şekilde, PowerShell'de):
bash
vcpkg install "opentelemetry-cpp[otlp-http]"

Projede vcpkg.json varsa (manifest modu) bunun yerine oraya ekleyin: vcpkg add port "opentelemetry-cpp[otlp-http]".

  1. CMakeLists.txt'te add_executable'dan sonra bu satırları ekleyin ve servisi vcpkg toolchain'iyle yeniden derleyin (cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake, ardından cmake --build build --config Release):
cmake
find_package(opentelemetry-cpp CONFIG REQUIRED)
target_include_directories(${PROJECT_NAME} PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
target_link_libraries(${PROJECT_NAME} PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})

Çalıştırılabilir dosyanın target'ı projenin adını taşımıyorsa ${PROJECT_NAME} yerine onun adını yazın.

  1. Klasörü, ardından /etc/spitfire-otel/<service-name>.env dosyasını oluşturun, şunu yapıştırın:
bash
sudo mkdir -p /etc/spitfire-otel
bash
IS_OTEL_ENABLED=true
OTEL_SERVICE_NAME=<service-name>
OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<spitfire>/otlp/v1/logs
OTEL_EXPORTER_OTLP_LOGS_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<tower>:4318/v1/metrics
OTEL_EXPORTER_OTLP_METRICS_HEADERS=authorization=sfcol_…
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
NO_PROXY=<tower>,<spitfire>
  1. İzni kısın: sudo chmod 600 /etc/spitfire-otel/<service-name>.env
  2. sudo systemctl edit <unit> açın, şunu yapıştırın:
ini
[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
  1. Yeni binary'yi yerine koyup yeniden başlatın: sudo systemctl daemon-reload && sudo systemctl restart <unit>
  2. Kontrol edin: servise birkaç istek gönderin; bir dakika içinde <service-name> servisi APM → Servisler → Servisler altında, span'leri (GET /items/:id) trace'lerinde görünür.
Not

Özel CA varsa CA dosyasını makineye koyup ortam dosyasına OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/spitfire-otel/ca.pem ekleyin; C++ exporter'ı bunu okur.

Conan ile kurmak

Conan Center'da opentelemetry-cpp 1.26.0 var (OTLP HTTP exporter'ı varsayılan olarak açık); kod ve CMakeLists.txt satırları aynı kalır.

  1. Paketi derleme klasörüne kurun:
bash
conan install --requires=opentelemetry-cpp/1.26.0 -o "opentelemetry-cpp/*:with_otlp_http=True" \
  -g CMakeDeps -g CMakeToolchain --build=missing --output-folder=build
  1. Conan'ın toolchain'iyle derleyin: cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release && cmake --build build

Docker

  1. Kod değişikliklerini yapın (Linux 1–4. adım) ve binary'yi image'da bugünkü gibi derleyin; vcpkg ve Conan varsayılan olarak opentelemetry-cpp, curl ve protobuf'u binary'ye bağlar.
  2. Son image'da https://<spitfire> için CA sertifikaları olmalı (Debian/Ubuntu'da: RUN apt-get update && apt-get install -y ca-certificates).
  3. Ortam dosyasını (Linux 5. adım) Docker makinesinde /etc/spitfire-otel/<service-name>.env olarak kaydedin.
  4. Çalıştırın: docker run --env-file /etc/spitfire-otel/<service-name>.env … ya da compose'da servisin altına env_file: /etc/spitfire-otel/<service-name>.env.
  5. Ortam dosyası değişince konteyneri yeniden oluşturun (restart yetmez): docker compose up -d --force-recreate <service>

Kubernetes

  1. Image'ı Docker bölümündeki gibi hazırlayın.
  2. Ortam dosyasını (Linux 5. adım) <service-name>.env olarak kaydedip Secret yapın:
bash
kubectl create secret generic <service-name>-otel --from-env-file=<service-name>.env \
  --dry-run=client -o yaml | kubectl apply -f -
  1. Deployment'ta container'ın altına ekleyin:
yaml
envFrom:
  - secretRef:
      name: <service-name>-otel
  1. Yeniden başlatın: kubectl rollout restart deployment/<deployment>

Windows (servis)

  1. Kod değişikliklerini yapın (Linux 1–4. adım) ve .exe'yi yeniden derleyin (vcpkg triplet'i x64-windows).
  2. Yönetici PowerShell'de <windows-service> yerine servisin adını (Get-Service listesindeki Name) yazıp çalıştırın:
powershell
$Service = "<windows-service>"
$IS_OTEL_ENABLED = "true"
$Otel = @(
  "IS_OTEL_ENABLED=$IS_OTEL_ENABLED",
  "OTEL_SERVICE_NAME=<service-name>",
  "OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>",
  "OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf",
  "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces",
  "OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…",
  "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<spitfire>/otlp/v1/logs",
  "OTEL_EXPORTER_OTLP_LOGS_HEADERS=authorization=sfotlp_…",
  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<tower>:4318/v1/metrics",
  "OTEL_EXPORTER_OTLP_METRICS_HEADERS=authorization=sfcol_…",
  "OTEL_TRACES_SAMPLER=parentbased_traceidratio",
  "OTEL_TRACES_SAMPLER_ARG=0.1",
  "NO_PROXY=<tower>,<spitfire>"
)
$Key = "HKLM:\SYSTEM\CurrentControlSet\Services\$Service"
$Keep = @((Get-ItemProperty $Key).Environment | Where-Object { $_ -and $_ -notmatch '^(IS_OTEL_ENABLED|OTEL_|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
Restart-Service -Name $Service -Force

Framework: cpp-httplib

cpp-httplib Enstrümantasyon Server span
0.14+ src/otel.h içindeki otel::StartServerSpan / otel::EndServerSpan GET /items/:id (http.route)

Doğrulandı: 2026-11-10. Kaynak: cpp-httplib, opentelemetry-cpp http server örneği.

  1. Kod değişikliklerini Linux 1–4. adımlardaki gibi yapın; her handler span'ini route kalıbı ve req.get_header_value ile otel::StartServerSpan'den açar (2. adım).
  2. Handler'ların server span açtığına bakın (<project>: CMakeLists.txt'in olduğu klasör):
bash
grep -q StartServerSpan <project>/src/otel.h && grep -rq 'otel::StartServerSpan' <project>/src && echo OK

Kapatma ve kaldırma

  1. Kapatmak: IS_OTEL_ENABLED=false yapıp servisi yeniden başlatın (Windows'ta betiği yeniden çalıştırın). Kod kalır, Setup o zaman hiçbir şey yapmaz.
  2. Kaldırmak: src/otel.h dosyasını, #include "otel.h" ve otel:: satırlarını ve CMakeLists.txt'e eklenen üç satırı silip yeniden derleyin; sudo systemctl revert <unit> ve sudo rm -r /etc/spitfire-otel; Windows'ta servisin Environment değerinden OTel satırlarını silin.

Sık karşılaşılan sorunlar

Hiç trace gelmiyorsa önce Doğrulama adımlarını uygulayın. En sık karşılaşılan hata tablonun ilk satırı: CMake'in vcpkg toolchain'i olmadan çalıştırılması.

Belirti Neden Çözüm
Could not find a package configuration file provided by "opentelemetry-cpp" CMake vcpkg'nin (ya da Conan'ın) toolchain'ini kullanmıyor Linux 4. adımdaki gibi -DCMAKE_TOOLCHAIN_FILE=… ekleyin
opentelemetry/exporters/otlp/otlp_http_exporter_factory.h: No such file Paket OTLP HTTP exporter'ı olmadan kurulmuş vcpkg install "opentelemetry-cpp[otlp-http]" (özellik köşeli parantezde)
undefined reference to opentelemetry::… Kütüphanelerin yalnız bir kısmı bağlanmış ${OPENTELEMETRY_CPP_LIBRARIES} bağlayın (Linux 4. adım)
Span'lerin Spitfire testinden parent'ı yok Span StartServerSpan ile açılmıyor ya da başlık fonksiyonu başka başlık döndürüyor İsteğin kendi başlık aramasını verin (Linux 2. adım)

İlgili sayfalar