diff --git a/content/en/docs/instrumentation/cpp/getting-started-new.md b/content/en/docs/instrumentation/cpp/getting-started-new.md index 81c64e74f734..ca08fdfe900d 100644 --- a/content/en/docs/instrumentation/cpp/getting-started-new.md +++ b/content/en/docs/instrumentation/cpp/getting-started-new.md @@ -1,69 +1,162 @@ --- title: Getting Started -description: Get telemetry for your app in less than 5 minutes! +description: Get telemetry for your app in less than 10 minutes! cSpell:ignore: rolldice weight: 10 --- This page will show you how to get started with OpenTelemetry in C++. -You will learn how you can instrument a simple C++ application automatically, in -such a way that [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/) and [logs](/docs/concepts/signals/logs/) are emitted to the console. +You will learn how to instrument a simple C++ application automatically, +such that [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/) and [logs](/docs/concepts/signals/logs/) are emitted to the terminal. ## Prerequisites Ensure that you have the following installed locally: - Git -- C++ compiler supporting C++ version >= 11 +- C++ compiler supporting C++ version >= 14 - Make - CMake version >= 3.1 -- [Conan](https://conan.io/) ## Example Application -The following example uses a basic [Oat++](https://oatpp.io/) application. If you are not using -Oat++, that's OK - you can use OpenTelemetry C++ with other web frameworks -as well, such as Crow and POCO. For a complete list of -libraries for supported frameworks, see the [registry](/ecosystem/registry/?language=cpp). +The following example uses a basic [Oat++](https://oatpp.io/) application. If you are +not using Oat++, that's OK - you can use OpenTelemetry C++ with any other web frameworks as well. ## Dependencies -To begin, set up an environment in a new directory called `cpp-simple`. Within -that directory, install the oatpp locally using package manager Conan. +**To begin, we will install Oatpp locally using the [source code](https://github.com/oatpp) and `make`, following these general steps:** -Create a Conan profile for your project +1. Download oatpp source code: + +Obtain the oatpp source code. You can either download the source code from the oatpp Github repository or clone it using Git. + +```bash +git clone https://github.com/oatpp/oatpp.git +``` + +2. Navigate to the oatpp directory: + +Access the oatpp directory in your terminal. + +```bash +cd oatpp +``` + +3. Build oatpp: + +Build oatpp using the `make` command. This command will trigger the build process specified in the Makefile included in the oatpp source code. ```bash -conan profile new cpp-simple --detect +make ``` +4. Install oatpp: -Install oatpp in your project directory using Conan +This command will install the built oatpp library and headers on your system, making it accesible for development in your project. ```bash -conan install . --profile=cpp-simple +make install ``` -This will create a `conanfile.txt` file in your project directory, which includes oatpp as a dependency. +**Next, install and build [OpenTelemetry C++](https://github.com/open-telemetry/opentelemetry-cpp) locally using CMake, following these general steps:** -Now open the `conanfile.txt` file in a text editor and add oatpp as a dependency: +1. Clone the OpenTelemetry C++ repository: -```plaintext -[requires] -oatpp/1.2.0 # Use the desired version of oatpp +Clone the OpenTelemetry C++ GitHub repository to your local machine. -[generators] -cmake +```bash +git clone https://github.com/open-telemetry/opentelemetry-cpp.git ``` -Finally run the following command to locally install oatpp the project dependency: +2. Navigate to the OpenTelemetry C++ SDK directory: + +Change your working directory to the OpenTelemetry C++ SDK directory. ```bash -conan install . +cd openTelemetry-cpp ``` +3. Create a build directory: + +It's a good practice to create a seperate directory for the build files to keep your source directory clean. + +```bash +mkdir build +cd build +``` + +4. Configure and generate the build system: + +Run the CMake from the build directory to configure the build. + +```bash +cmake .. +``` + +5. Build the project: + +After configuring the build system, execute the build process. + +```bash +cmake --build . +``` + +**Finally, create a new project directory called `roll-dice`.** + ## Create and launch an HTTP Server +**Integrate oatpp in your project:** + +In your `roll-dice` project, utilize the oatpp library by referencing the oatpp headers and linking them when compiling your project.. + +Create a file called `CMakeLists.txt` to define the oatpp library directories, include paths, and link against oatpp during the compilation process. + +Here is what `CMakeLists.txt` might look like: + +```cmake +cmake_minimum_required(VERSION 3.1) + +# Set C++ standard (e.g., C++17) +set(CMAKE_CXX_STANDARD 17) + +set(project_name my-oatpp-project) + +# Define your project's source files +set(SOURCES + main.cpp # Add your source files here +) + +# Create an executable target +add_executable(myapp ${SOURCES}) + +set(OATPP_ROOT /path/to/oatpp) +set(OATPP_LIB /path/to/oatpp/lib) + +#set the path to the directory containing "oatpp" package configuration files +include_directories(${OATPP_ROOT}/src) +target_link_libraries(myapp PRIVATE ${OATPP_LIB}/liboatpp.a) + +``` +Replace `/path/to/oatpp` and `/path/to/oatpp/lib` with the actual path leading to the oatpp and oatpp library header files within your local installation. + +**Note:** + +`${OATPP_ROOT}/src` should contain header filies with `.hpp` extensions. + +You can manually search for the oatpp library using terminal commands. For Instance, on Unix-based systems, the `find` command could be used: +```bash +find / -name 'liboatpp.a' 2>/dev/null +``` + +**Create a simple API for rolling a dice:** + +Our application should do the following: + +* Initialize an HTTP router and set up a request handler to generate a random number as the response when a GET request is made to the `/rolldice` endpoint. +* Next, create a connection handler, a connection provider, and start the server on . +* Lastly, initialize and run the application within the main function. + In that same folder, create a file called `main.cpp` and add the following code to the file: ```cpp @@ -76,7 +169,6 @@ In that same folder, create a file called `main.cpp` and add the following code using namespace std; - class Handler : public oatpp::web::server::HttpRequestHandler { public: shared_ptr handle(const shared_ptr& request) override { @@ -108,38 +200,9 @@ int main() { } ``` +**Build and run your application:** -Create another file called `CMakeLists.txt` and it is used to define the build process for -your C++ project, inclduing how to compile and link your oatpp and OpenTelemetry -application. Here is what `CMakeLists.txt` might look like: - -```plaintext -cmake_minimum_required(VERSION 3.1) -set(project_name my-oatpp-project) - -# Set C++ standard (e.g., C++17) -set(CMAKE_CXX_STANDARD 17) - -# Find Conan-generated build information -include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) -conan_basic_setup(TARGETS) # Use TARGETS to link Conan libraries - - -# Define your project's source files -set(SOURCES - main.cpp # Add your source files here -) - -# Create an executable target -add_executable(myapp ${SOURCES}) - -# Link Conan libraries (oatpp and its dependencies) -target_link_libraries(myapp PRIVATE CONAN_PKG::oatpp) - -``` - -Build and run the application with the following CMake commands, then open - in your browser to ensure it is working. +Build and run the application with the following CMake commands. ```bash mkdir build @@ -148,40 +211,27 @@ cmake .. cmake --build . ``` -After successfully building your project, you can run the generated executable: +After successfully building your project, you can run the generated executable. ```bash ./myapp ``` -## Instrumentation +Then, open in your browser to ensure it is working. -To begin, install and build `openTelemetry-cpp` library locally using CMake. -Naviagte outside of your `cpp-simple` directory and run the following commands: -```bash -git clone https://github.com/open-telemetry/opentelemetry-cpp -cd opentelemetry-cpp -mkdir build && cd build -cmake .. -make -make install -``` +## Instrumentation + +**Integrate OpenTelemetry in your project:** To add OpenTelemetry to your application, update the `CMakeLists.txt` file with the following additional dependencies: -```plaintext -cmake_minimum_required(VERSION 3.1) -set(project_name my-oatpp-project) - +```cmake # Set C++ standard (e.g., C++17) -set(CMAKE_CXX_STANDARD 14) - -# Find Conan-generated build information -include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) -conan_basic_setup(TARGETS) # Use TARGETS to link Conan libraries +set(CMAKE_CXX_STANDARD 17) +set(project_name my-oatpp-project) # Define your project's source files set(SOURCES @@ -191,46 +241,73 @@ set(SOURCES # Create an executable target add_executable(myapp ${SOURCES}) -# Link Conan libraries (oatpp and its dependencies) -target_link_libraries(myapp PRIVATE CONAN_PKG::oatpp) - - -#set the path to the directory containing "opentelemetry-cpp" package configuration files -find_package(opentelemetry-cpp CONFIG REQUIRED) -message(STATUS "Using opentelemetry-cpp at: ${OPENTELEMETRY_CPP_INCLUDE_DIRS}") -message(STATUS "Using opentelemetry-cpp libraries: ${OPENTELEMETRY_CPP_LIBRARIES}") - - -#first include directories -target_link_directories(AlcorControlAgent PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS}) -target_link_directories(AlcorControlAgent PRIVATE /Users/q/Desktop/opentelemetry-cpp/) -target_link_directories(AlcorControlAgent PRIVATE /Users/q/Desktop/opentelemetry-cpp//sdk) +set(OATPP_ROOT /path/to/oatpp) +set(OATPP_LIB /path/to/oatpp/lib) +set(OPENTELEMETRY_ROOT /path/to/opentelemetry-cpp) + +#set the path to the directory containing "oatpp" package configuration files +include_directories(${OATPP_ROOT}/src) +target_link_libraries(myapp PRIVATE ${OATPP_LIB}/liboatpp.a) + +#set the path to the directory containing "pentelemetry-cpp" package configuration files +include_directories(${OPENTELEMETRY_ROOT}/api/include) +include_directories(${OPENTELEMETRY_ROOT}/sdk/include) +include_directories(${OPENTELEMETRY_ROOT}/sdk/src) +include_directories(${OPENTELEMETRY_ROOT}/exporters/ostream/include) +target_link_libraries(myapp PRIVATE ${OPENTELEMETRY_ROOT}/build/sdk/src/trace/libopentelemetry_trace.a + ${OPENTELEMETRY_ROOT}/build/sdk/src/common/libopentelemetry_common.a + ${OPENTELEMETRY_ROOT}/build/exporters/ostream/libopentelemetry_exporter_ostream_span.a + ${OPENTELEMETRY_ROOT}/build/ext/src/http/client/curl/libopentelemetry_http_client_curl.a + ${OPENTELEMETRY_ROOT}/build/sdk/src/resource/libopentelemetry_resources.a) ``` +Replace `/path/to/opentelemetry-cpp` with the actual path leading to the opentelemetry-cpp sdk within your local installation. -Update the `main.cpp` file with code to initialize a tracer and to emit spans when the `rolldice` request handler is called: +**OpenTelemetry tracing configuration:** + +Update the `main.cpp` file with code to initialize a tracer and to emit spans when the `/rolldice` request handler is called: ```cpp #include "oatpp/web/server/HttpConnectionHandler.hpp" #include "oatpp/network/Server.hpp" #include "oatpp/network/tcp/server/ConnectionProvider.hpp" + +#include "opentelemetry/exporters/ostream/span_exporter_factory.h" +#include "opentelemetry/sdk/trace/exporter.h" +#include "opentelemetry/sdk/trace/processor.h" +#include "opentelemetry/sdk/trace/simple_processor_factory.h" +#include "opentelemetry/sdk/trace/tracer_provider_factory.h" +#include "opentelemetry/trace/provider.h" + #include #include #include - -// sdk::TracerProvider is just used to call ForceFlush and prevent to cancel running exportings when -// destroy and shutdown exporters.It's optional to users. -#include "sdk/trace/tracer_provider.h" - using namespace std; - -opentelemetry::api::trace::Tracer tracer = opentelemetry::api::Provider::GetTracer("your_component"); - -auto span = tracer.StartSpan("your_operaion"); +namespace trace_api = opentelemetry::trace; +namespace trace_sdk = opentelemetry::sdk::trace; +namespace trace_exporter = opentelemetry::exporter::trace; + +namespace { + void InitTracer() { + auto exporter = trace_exporter::OStreamSpanExporterFactory::Create(); + auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter)); + std::shared_ptr provider = + trace_sdk::TracerProviderFactory::Create(std::move(processor)); + //set the global trace provider + trace_api::Provider::SetTracerProvider(provider); + } + void CleanupTracer() { + std::shared_ptr none; + trace_api::Provider::SetTracerProvider(none); + } + +} class Handler : public oatpp::web::server::HttpRequestHandler { public: shared_ptr handle(const shared_ptr& request) override { + auto tracer = opentelemetry::trace::Provider::GetTracerProvider()->GetTracer("my-app-tracer"); + auto span = tracer->StartSpan("RollDice"); int low = 1; int high = 7; srand((int)time(0)); @@ -238,6 +315,7 @@ public: // Convert a std::string to oatpp::String const string response = to_string(random); return ResponseFactory::createResponse(Status::CODE_200, response.c_str()); + span->End(); } }; @@ -253,32 +331,48 @@ void run() { int main() { oatpp::base::Environment::init(); + InitTracer(); run(); oatpp::base::Environment::destroy(); + CleanupTracer(); return 0; } -span.End(); ``` -Build your project again: +**Build your project again:** ```bash -mkdir build cd build cmake .. cmake --build . ``` -After successfully building your project, you can run the generated executable: +**After successfully building your project, you can run the generated executable:** ```bash ./myapp ``` -When you send a request to the server at , you will see a span being emitted to the console (output is pretty printed for convenience): +When you send a request to the server at , you will see a span being emitted to the terminal: + ```json -json data type goes here +{ + "name" : "RollDice", + "trace_id": "f47bea385dc55e4d17470d51f9d3130b", + "span_id": "deed994b51f970fa", + "tracestate" : , + "parent_span_id": "0000000000000000", + "start": 1698991818716461000, + "duration": 64697, + "span kind": "Internal", + "status": "Unset", + "service.name": "unknown_service", + "telemetry.sdk.language": "cpp", + "telemetry.sdk.name": "opentelemetry", + "telemetry.sdk.version": "1.11.0", + "instr-lib": "my-app-tracer" +} ``` ## Next Steps