Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updated version of the C++ Getting Started with a Roll The Dice #3423

Merged
merged 68 commits into from
Feb 9, 2024
Merged
Changes from 4 commits
Commits
Show all changes
68 commits
Select commit Hold shift + click to select a range
2210283
Created an updated version of the C++ Getting Started with a Roll The…
Akhaled19 Oct 20, 2023
7138098
resolves comments for c++ roll dice getting started
Akhaled19 Nov 4, 2023
af083d6
Resolves comments and edits c++ getting started file
Akhaled19 Nov 5, 2023
fbad7e1
Resolves comments and edits c++ getting started file. take two.
Akhaled19 Nov 5, 2023
2e4bed9
Created an updated version of the C++ Getting Started with a Roll The…
Akhaled19 Oct 20, 2023
bd9af38
resolves comments for c++ roll dice getting started
Akhaled19 Nov 4, 2023
9bf5b22
Resolves comments and edits c++ getting started file
Akhaled19 Nov 5, 2023
47c7c32
Resolves comments and edits c++ getting started file. take two.
Akhaled19 Nov 5, 2023
f48a51c
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
612c6a2
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
f215cd9
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
bf4e9e2
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
44a04ae
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
ff5d9dd
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
59f6ba6
Update content/en/docs/instrumentation/cpp/getting-started-new.md
Akhaled19 Nov 16, 2023
12e580c
Merge branch 'open-telemetry:main' into azal_c++_gs
Akhaled19 Nov 22, 2023
3b00e96
grammar fix
Akhaled19 Nov 22, 2023
f323352
addressed comments and added a visual representation of the directory…
Akhaled19 Nov 29, 2023
891ac24
Merge branch 'main' into azal_c++_gs
Akhaled19 Nov 29, 2023
0b2d9c7
replaced old getting started
Akhaled19 Nov 30, 2023
93dba8a
Merge branch 'main' into azal_c++_gs
Akhaled19 Dec 1, 2023
5b5abb8
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 7, 2023
31ed747
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 7, 2023
0f4f445
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 7, 2023
c8bdac8
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 7, 2023
16eaa6b
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
e578e69
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
a50d1bf
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
bde090b
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
a802826
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
e181b92
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
7da7542
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
643d6a6
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
3739d78
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
1c7d608
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
50f7998
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
d383f7b
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
7479bb0
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
7d4c91b
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
f9fe617
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
12c60f0
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
03c12b7
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
b2ed603
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
310af3e
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
eb11179
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
69c6fea
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
15bfab0
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
5c7eeae
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
30abfbe
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
093d9a7
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
11bc416
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
5741082
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
14982cf
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Dec 18, 2023
2aa6b0e
Merge branch 'main' into azal_c++_gs
Akhaled19 Dec 18, 2023
8bbfaf3
fixes CMakeList.txt andminorr styling
Akhaled19 Jan 27, 2024
7160fe3
fixes naming and adds instructions in setup
Akhaled19 Jan 29, 2024
062b00b
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 1, 2024
1158b10
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 1, 2024
0827b50
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 1, 2024
dc0142d
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 1, 2024
cbb32a0
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 9, 2024
faec45f
Update content/en/docs/instrumentation/cpp/getting-started.md
Akhaled19 Feb 9, 2024
77399f6
adds optimizations to main and updates text
Akhaled19 Feb 9, 2024
de050fc
fix merge conflict
svrnm Feb 9, 2024
b215ddc
fix format and refcache
svrnm Feb 9, 2024
42744df
fix markdown issues
svrnm Feb 9, 2024
19de742
fix link copy and paste issue
svrnm Feb 9, 2024
be7dec5
fix link copy and paste issue no.2
svrnm Feb 9, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
388 changes: 388 additions & 0 deletions content/en/docs/instrumentation/cpp/getting-started-new.md
svrnm marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,388 @@
---
title: Getting Started
description: Get telemetry for your app in less than 5 minutes!
cSpell:ignore: rolldice
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
weight: 10
---

This page will show you how to get started with OpenTelemetry in C++.

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 >= 14
- Make
- CMake version >= 3.1

## 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 any other web frameworks as well.
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved

## Dependencies

**To begin, we will install Oatpp locally using the [source code](https://github.com/oatpp) and `make`, following these general steps:**

Check warning on line 29 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (Oatpp)

1. Download oatpp source code:

Check warning on line 31 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (oatpp)

Obtain the oatpp source code. You can either download the source code from the oatpp Github repository or clone it using Git.

Check warning on line 33 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (oatpp)

Check warning on line 33 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (oatpp)

Check failure on line 33 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / TEXT linter

textlint terminology error

Incorrect usage of the term: “Github”, use “GitHub” instead
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved

```bash
git clone https://github.com/oatpp/oatpp.git
```

2. Navigate to the oatpp directory:

Check warning on line 39 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (oatpp)

Access the oatpp directory in your terminal.

Check warning on line 41 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (oatpp)

```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
make
```
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
4. Install oatpp:

This command will install the built oatpp library and headers on your system, making it accesible for development in your project.

Check warning on line 56 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (accesible)
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved

```bash
make install
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
```

**Next, install and build [OpenTelemetry C++](https://github.com/open-telemetry/opentelemetry-cpp) locally using CMake, following these general steps:**

1. Clone the OpenTelemetry C++ repository:

Clone the OpenTelemetry C++ GitHub repository to your local machine.

```bash
git clone https://github.com/open-telemetry/opentelemetry-cpp.git
```

2. Navigate to the OpenTelemetry C++ SDK directory:

Change your working directory to the OpenTelemetry C++ SDK directory.

```bash
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.

Check warning on line 82 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (seperate)
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved

```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 ..
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
```

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})

Check warning on line 131 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (myapp)

set(OATPP_ROOT /path/to/oatpp)

Check warning on line 133 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / SPELLING check

Unknown word (OATPP)
set(OATPP_LIB /path/to/oatpp/lib)

#set the path to the directory containing "oatpp" package configuration files
include_directories(${OATPP_ROOT}/src)
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
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 <localhost:8000>.
* 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
#include "oatpp/web/server/HttpConnectionHandler.hpp"
#include "oatpp/network/Server.hpp"
#include "oatpp/network/tcp/server/ConnectionProvider.hpp"
#include <cstdlib>
#include <ctime>
#include <string>

using namespace std;

class Handler : public oatpp::web::server::HttpRequestHandler {
public:
shared_ptr<OutgoingResponse> handle(const shared_ptr<IncomingRequest>& request) override {
int low = 1;
int high = 7;
srand((int)time(0));
int random = rand() % (high - low) + low;
// Convert a std::string to oatpp::String
const string response = to_string(random);
return ResponseFactory::createResponse(Status::CODE_200, response.c_str());
}
};

void run() {
auto router = oatpp::web::server::HttpRouter::createShared();
router->route("GET", "/rolldice", std::make_shared<Handler>());
auto connectionHandler = oatpp::web::server::HttpConnectionHandler::createShared(router);
auto connectionProvider = oatpp::network::tcp::server::ConnectionProvider::createShared({"localhost", 8000, oatpp::network::Address::IP_4});
oatpp::network::Server server(connectionProvider, connectionHandler);
OATPP_LOGI("MyApp", "Server running on port %s", connectionProvider->getProperty("port").getData());
server.run();
}

int main() {
oatpp::base::Environment::init();
run();
oatpp::base::Environment::destroy();
return 0;
}

```
**Build and run your application:**

Build and run the application with the following CMake commands.

```bash
mkdir build
cd build
cmake ..
cmake --build .
```

After successfully building your project, you can run the generated executable.

```bash
./myapp
```

Then, open <http://localhost:8080/rolldice> in your browser to ensure it is working.


## Instrumentation

**Integrate OpenTelemetry in your project:**

To add OpenTelemetry to your application, update the `CMakeLists.txt` file with the
following additional dependencies:

```cmake
# 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(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
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved
${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.

Check failure on line 263 in content/en/docs/instrumentation/cpp/getting-started-new.md

GitHub Actions / TEXT linter

textlint terminology error

Incorrect usage of the term: “sdk”, use “SDK” instead
Akhaled19 marked this conversation as resolved.
Show resolved Hide resolved

**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 <cstdlib>
#include <ctime>
#include <string>

using namespace std;
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<opentelemetry::trace::TracerProvider> provider =
trace_sdk::TracerProviderFactory::Create(std::move(processor));
//set the global trace provider
trace_api::Provider::SetTracerProvider(provider);
}
void CleanupTracer() {
std::shared_ptr<opentelemetry::trace::TracerProvider> none;
trace_api::Provider::SetTracerProvider(none);
}

}

class Handler : public oatpp::web::server::HttpRequestHandler {
public:
shared_ptr<OutgoingResponse> handle(const shared_ptr<IncomingRequest>& 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));
int random = rand() % (high - low) + low;
// Convert a std::string to oatpp::String
const string response = to_string(random);
return ResponseFactory::createResponse(Status::CODE_200, response.c_str());
span->End();
}
};

void run() {
auto router = oatpp::web::server::HttpRouter::createShared();
router->route("GET", "/rolldice", std::make_shared<Handler>());
auto connectionHandler = oatpp::web::server::HttpConnectionHandler::createShared(router);
auto connectionProvider = oatpp::network::tcp::server::ConnectionProvider::createShared({"localhost", 8000, oatpp::network::Address::IP_4});
oatpp::network::Server server(connectionProvider, connectionHandler);
OATPP_LOGI("MyApp", "Server running on port %s", connectionProvider->getProperty("port").getData());
server.run();
}

int main() {
oatpp::base::Environment::init();
InitTracer();
run();
oatpp::base::Environment::destroy();
CleanupTracer();
return 0;
}

```

**Build your project again:**

```bash
cd build
cmake ..
cmake --build .
```

**After successfully building your project, you can run the generated executable:**

```bash
./myapp
```

When you send a request to the server at <http://localhost:8080/rolldice>, you will see a span being emitted to the terminal:

```json
{
"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

Enrich your instrumentation generated automatically with
[manual instrumentation](/docs/instrumentation/cpp/manual) of your own
codebase. This gets you customized observability data.

Take a look at available
[Exporters](/docs/instrumentation/cpp/exporters/) that
generate telemetry data for popular frameworks and libraries.

[traces]: /docs/concepts/signals/traces/