{"id":19444364,"url":"https://github.com/skyapm/cpp2sky","last_synced_at":"2025-04-25T01:30:30.742Z","repository":{"id":39759907,"uuid":"304192773","full_name":"SkyAPM/cpp2sky","owner":"SkyAPM","description":"Distributed tracing and monitor SDK in CPP for Apache SkyWalking APM","archived":false,"fork":false,"pushed_at":"2023-12-12T14:38:18.000Z","size":231,"stargazers_count":52,"open_issues_count":13,"forks_count":18,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-04-20T09:18:22.083Z","etag":null,"topics":["cpp","observability","skywalking","tracer"],"latest_commit_sha":null,"homepage":"https://skywalking.apache.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SkyAPM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-10-15T02:53:57.000Z","updated_at":"2024-03-27T07:15:14.000Z","dependencies_parsed_at":"2023-12-12T15:51:19.022Z","dependency_job_id":null,"html_url":"https://github.com/SkyAPM/cpp2sky","commit_stats":{"total_commits":77,"total_committers":9,"mean_commits":8.555555555555555,"dds":0.2857142857142857,"last_synced_commit":"9b7e77216a67e33e5a5e52ed24134b74f774607e"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkyAPM%2Fcpp2sky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkyAPM%2Fcpp2sky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkyAPM%2Fcpp2sky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkyAPM%2Fcpp2sky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SkyAPM","download_url":"https://codeload.github.com/SkyAPM/cpp2sky/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250737797,"owners_count":21479087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","observability","skywalking","tracer"],"created_at":"2024-11-10T16:06:47.081Z","updated_at":"2025-04-25T01:30:30.409Z","avatar_url":"https://github.com/SkyAPM.png","language":"C++","readme":"# cpp2sky\n\n![cpp2sky test](https://github.com/SkyAPM/cpp2sky/workflows/cpp2sky%20test/badge.svg)\n\nDistributed tracing and monitor SDK in CPP for Apache SkyWalking APM. This SDK is compatible with C++ 17, C++ 14, and C++ 11.\n\n## Build\n\n#### Bazel\n\nDownload cpp2sky tarball with specified version.\n\n```\nhttp_archive(\n  name = \"com_github_skyapm_cpp2sky\",\n  sha256 = \u003cSHA256\u003e,\n  urls = [\"https://github.com/skyAPM/cpp2sky/archive/\u003cVERSION\u003e.tar.gz\"],\n)\n```\n\nAdd interface definition and library to your project.\n\n```\ncc_binary(\n  name = \"example\",\n  srcs = [\"example.cc\"],\n  deps = [\n    \"@com_github_skyapm_cpp2sky//cpp2sky:cpp2sky_interface\",\n    \"@com_github_skyapm_cpp2sky//source:cpp2sky_lib\"\n  ],\n)\n```\n\n#### Cmake\n\nYou can compile this project, according to the following steps:\n```\nstep 01: git clone git@github.com:SkyAPM/cpp2sky.git\nstep 02: git clone -b v9.1.0 https://github.com/apache/skywalking-data-collect-protocol.git ./3rdparty/skywalking-data-collect-protocol\nstep 03: git clone -b v1.46.6 https://github.com/grpc/grpc.git --recursive\nstep 04: cmake -S ./grpc -B ./grpc/build \u0026\u0026 cmake --build ./grpc/build --parallel 8 --target install\nstep 05: cmake -S . -B ./build \u0026\u0026 cmake --build ./build\n```\n\nYou can also use find_package to get target libary in your project. Like this:\n```\nfind_package(cpp2sky CONFIG REQUIRED)\ntarget_link_libraries(${PROJECT_NAME} cpp2sky::cpp2sky proto_lib)\n```\nOf course, if OS is similar to Unix, you can also use pkgconfig to build the project. Like this:\n```\nfind_package(PkgConfig REQUIRED)\npkg_check_modules(CPP2SKY_PKG REQUIRED cpp2sky)\n```\n\nNote:\n- If you want to build this project over c11, you must update grpc version(current version:v1.46.6).\n- Only test cmake using Centos and Ubuntu.\n\n#### Develop\n\nGenerate `compile_commands.json` for this repo by `bazel run :refresh_compile_commands`. Thank https://github.com/hedronvision/bazel-compile-commands-extractor for it provide the great script/tool to make this so easy!\n\n#### Docs\n\ncpp2sky configration is based on protobuf, and docs are generated by [protodoc](https://github.com/etcd-io/protodoc). If you have any API change, you should run below.\n\n```\nprotodoc --directory=./cpp2sky --parse=\"message\" --languages=\"C++\" --title=cpp2sky config --output=docs/README.md\n```\n\n## Basic usage\n\n#### Config\n\ncpp2sky provides simple configuration for tracer. API docs are available at `docs/README.md`.\nThe detail information is described in [official protobuf definition](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Tracing.proto#L57-L67).\n\n```cpp\n#include \u003ccpp2sky/config.pb.h\u003e\n\nint main() {\n  using namespace cpp2sky;\n\n  static const std::string service_name = \"service_name\";\n  static const std::string instance_name = \"instance_name\";\n  static const std::string oap_addr = \"oap:12800\";\n  static const std::string token = \"token\";\n\n  TracerConfig tracer_config;\n\n  config.set_instance_name(instance_name);\n  config.set_service_name(service_name);\n  config.set_address(oap_addr);\n  config.set_token(token);\n}\n```\n\n#### Create tracer\n\nAfter you constructed config, then setup tracer. Tracer supports gRPC reporter only, also TLS adopted gRPC reporter isn't available now.\nTLS adoption and REST tracer will be supported in the future.\n\n```cpp\nTracerConfig tracer_config;\n\n// Setup\n\nTracerPtr tracer = createInsecureGrpcTracer(tracer_config);\n```\n\n#### Fetch propagated span\n\ncpp2sky supports only HTTP tracer now.\nTracing span will be delivered from `sw8` and `sw8-x` HTTP headers. For more detail, please visit [here](https://github.com/apache/skywalking/blob/08781b41a8255bcceebb3287364c81745a04bec6/docs/en/protocols/Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md)\nThen, you can create propagated span object by decoding these items.\n\n```cpp\nSpanContextSharedPtr parent_span = createSpanContext(parent);\n```\n\n#### Create span\n\nFirst, you must create tracing context that holds all spans, then crete initial entry span.\n\n```cpp\nTracingContextSharedPtr tracing_context = tracer-\u003enewContext();\nTracingSpanSharedPtr tracing_span = tracing_context-\u003ecreateEntrySpan();\n```\n\nAfter that, you can create another span to trace another workload, such as RPC to other services.\nNote that you must have parent span to create secondary span. It will construct parent-child relation when analysis.\n\n```cpp\nTracingSpanSharedPtr current_span = tracing_context-\u003ecreateExitSpan(current_span);\n```\n\nAlternative approach is RAII based one. It is used like below,\n\n```cpp\n{\n  StartEntrySpan entry_span(tracing_context, \"sample_op1\");\n  {\n    StartExitSpan exit_span(tracing_context, entry_span.get(), \"sample_op2\");\n\n    // something...\n  }\n}\n```\n\n#### Send segment to OAP\n\nNote that TracingContext is unique pointer. So when you'd like to send data, you must move it and don't refer after sending,\nto avoid undefined behavior.\n\n```cpp\nTracingContextSharedPtr tracing_context = tracer-\u003enewContext();\nTracingSpanSharedPtr tracing_span = tracing_context-\u003ecreateEntrySpan();\n\ntracing_span-\u003estartSpan(\"sample_workload\");\ntracing_span-\u003eendSpan();\n\ntracer-\u003ereport(std::move(tracing_context));\n```\n\n#### Skywalking CDS\n\nC++ agent implements Skywalking CDS feature it allows to change bootstrap config dynamically from the response of sync request, invoked from this periodically.\nDynamically configurable values are described in description of properties on `docs/README.md'.\n\n```cpp\nTracerConfig config;\n// If you set this value as zero, CDS request won't occur.\nconfig.set_cds_request_interval(5); // CDS request interval should be 5sec\n```\n\nIf you are using Consul KVS as backend, we could put configuration value through HTTP request.\n\n```yaml\nconfigurations:\n  service_name:\n    ignore_suffix: '/ignore, /hoge'\n```\n\nAfter setup configurations, try to put values with\n\n```\ncurl --request PUT --data-binary \"@./config.yaml\" http://localhost:8500/v1/kv/configuration-discovery.default.agentConfigurations\n```\n\n## Trace and Log integration\n\ncpp2sky implements to output logs which is the key to integrate with actual tracing context.\n\n#### Supported Logger\n\n- [spdlog](https://github.com/gabime/spdlog)\n\n```cpp\n#include \u003cspdlog/spdlog.h\u003e\n#include \u003ccpp2sky/trace_log.h\u003e\n\nint main() {\n  auto logger = spdlog::default_logger();\n  // set_pattern must be called.\n  logger-\u003eset_pattern(logFormat\u003cdecltype(logger)::element_type\u003e());\n\n  // It will generate log message as follows.\n  //\n  // {\"level\": \"warning\", \"msg\": \"sample\", \"SW_CTX\": [\"service\",\"instance\",\"trace_id\",\"segment_id\",\"span_id\"]}\n  //\n  logger-\u003ewarn(tracing_context-\u003elogMessage(\"sample\"));\n}\n```\n\n## Security\n\nIf you've found any security issues, please read [Security Reporting Process](https://github.com/SkyAPM/cpp2sky/blob/main/SECURITY.md) and take described steps.\n\n## LICENSE\n\nApache 2.0 License. See [LICENSE](https://github.com/SkyAPM/cpp2sky/blob/main/LICENSE) for more detail.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyapm%2Fcpp2sky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskyapm%2Fcpp2sky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyapm%2Fcpp2sky/lists"}