diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ee3cca52f2..92815ba556 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,6 +97,13 @@ git commit git push fork feature ``` +If you made changes to the Markdown documents (`*.md` files), install the latest +[`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli) and run: + +```sh +markdownlint . +``` + Open a pull request against the main `opentelemetry-cpp` repo. To run tests locally, please read the [CI instructions](ci/README.md). @@ -144,6 +151,14 @@ If none of the above worked and the PR has been stuck for more than 2 weeks, the owner should bring it to the OpenTelemetry C++ SIG meeting. See [README.md](README.md#contributing) for the meeting link. +## Design Choices + +As with other OpenTelemetry clients, opentelemetry-cpp follows the +[opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification). + +It's especially valuable to read through the [library +guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md). + ## Useful Resources Hi! If you’re looking at this document, these resources will provide you the @@ -168,43 +183,13 @@ the C++ repository. * The OpenTelemetry Specification describes the requirements and expectations of for all OpenTelemetry implementations. -* Read through the [OpenTelemetry - Collector](https://github.com/open-telemetry/opentelemetry-collector) GitHub - repository. - * This repository has a lot of good information surrounding the OpenTelemetry - ecosystem. At the top of the - **[readme](https://github.com/open-telemetry/opentelemetry-collector/blob/main/README.md)**, - there are multiple links that give newcomers a good idea of what the project - is about and how to get involved in it. -* Read through the OpenTelemetry Python documentation +* Read through the OpenTelemetry C++ documentation * The - [API](https://opentelemetry-python.readthedocs.io/en/stable/api/api.html) + [API](https://opentelemetry-cpp.readthedocs.io/en/latest/api/api.html) and - [SDK](https://opentelemetry-python.readthedocs.io/en/stable/sdk/sdk.html) + [SDK](https://opentelemetry-cpp.readthedocs.io/en/latest/sdk/sdk.html) documentation provides a lot of information on what the classes and their - functions are used for. Since there is currently minimal documentation for - C++, use the Python repository’s extensive documentation to learn more about - how the API and SDK work. - -### Code Examples - -* Follow the [simple trace - example](https://github.com/open-telemetry/opentelemetry-cpp/pull/92) for an - introduction to basic OpenTelemetry functionality in C++. Currently the - example can be found in [PR - #94](https://github.com/open-telemetry/opentelemetry-cpp/pull/94). - -* Read through the [Java Quick-Start - Guide](https://github.com/open-telemetry/opentelemetry-java/blob/main/QUICKSTART.md). - This shows you how the classes and functions will interact in simple and easy - to digest examples. -* Take a look at this [Java SDK - example](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples/sdk-usage). - This shows a good use case of the SDK using stdout exporter. -* Take a look at the [Java Jaeger - example](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples/jaeger). - This provides a brief introduction to the Jaeger exporter, its interface, and - how to interact with the service. + functions are used for. Please contribute! You’re welcome to add more information if you come across any helpful resources. diff --git a/README.md b/README.md index 659bf15c56..ac866ec985 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ of the current project. | Platform | Build type | |---------------------------------------------------------------------|---------------| -| ubuntu-18.04 (Default GCC Compiler - 7.5.0) | CMake, Bazel | +| ubuntu-20.04 (Default GCC Compiler - 9.3.0) | CMake, Bazel | | ubuntu-18.04 (GCC 4.8 with -std=c++11 flag) | CMake [1] | | ubuntu-20.04 (Default GCC Compiler - 9.3.0 with -std=c++20 flags) | CMake, Bazel | | macOS 10.15 (Xcode 12.2) | Bazel | diff --git a/docs/public/sdk/GettingStarted.rst b/docs/public/sdk/GettingStarted.rst index fcdce5b846..dc982fc391 100644 --- a/docs/public/sdk/GettingStarted.rst +++ b/docs/public/sdk/GettingStarted.rst @@ -66,7 +66,7 @@ OpenTelemetry offers six tracing exporters out of the box: // otlp http exporter opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts; - opts.url = "http://localhost:4317/v1/traces"; + opts.url = "http://localhost:4318/v1/traces"; auto otlp_http_exporter = std::unique_ptr(new opentelemetry::exporter::otlp::OtlpHttpExporter(opts)); diff --git a/examples/otlp/README.md b/examples/otlp/README.md index cd85a392a1..0f6579288e 100644 --- a/examples/otlp/README.md +++ b/examples/otlp/README.md @@ -32,19 +32,18 @@ OpenTelemetry Collector with an OTLP receiver by running: - On Unix based systems use: ```console -docker run --rm -it -p 4317:4317 -p 55681:55681 -v $(pwd)/examples/otlp:/cfg otel/opentelemetry-collector:0.19.0 --config=/cfg/opentelemetry-collector-config/config.dev.yaml +docker run --rm -it -p 4317:4317 -p 4318:4318 -v $(pwd)/examples/otlp:/cfg otel/opentelemetry-collector:0.19.0 --config=/cfg/opentelemetry-collector-config/config.dev.yaml ``` - On Windows use: ```console -docker run --rm -it -p 4317:4317 -p 55681:55681 -v "%cd%/examples/otlp":/cfg otel/opentelemetry-collector:0.19.0 --config=/cfg/opentelemetry-collector-config/config.dev.yaml +docker run --rm -it -p 4317:4317 -p 4318:4318 -v "%cd%/examples/otlp":/cfg otel/opentelemetry-collector:0.19.0 --config=/cfg/opentelemetry-collector-config/config.dev.yaml ``` -Note that the OTLP exporter connects to the Collector at `localhost:4317` by -default. This can be changed with first argument from command-line, for example: +Note that the OTLP gRPC and HTTP exporters connects to the Collector at `localhost:4317` and `localhost:4318:/v1/traces` respectively. This can be changed with first argument from command-line, for example: `./example_otlp_grpc gateway.docker.internal:4317` and -`./example_otlp_http gateway.docker.internal:55681/v1/traces`. +`./example_otlp_http gateway.docker.internal:4318/v1/traces`. Once you have the Collector running, see [CONTRIBUTING.md](../../CONTRIBUTING.md) for instructions on building and diff --git a/examples/otlp/opentelemetry-collector-config/config.dev.yaml b/examples/otlp/opentelemetry-collector-config/config.dev.yaml index d3fbfd8834..6eb0b28fcf 100644 --- a/examples/otlp/opentelemetry-collector-config/config.dev.yaml +++ b/examples/otlp/opentelemetry-collector-config/config.dev.yaml @@ -7,7 +7,7 @@ receivers: grpc: endpoint: 0.0.0.0:4317 http: - endpoint: "0.0.0.0:55681" + endpoint: "0.0.0.0:4318" cors_allowed_origins: - '*' service: diff --git a/exporters/etw/include/opentelemetry/exporters/etw/etw_logger.h b/exporters/etw/include/opentelemetry/exporters/etw/etw_logger.h index 7ad67f049a..00653838bc 100644 --- a/exporters/etw/include/opentelemetry/exporters/etw/etw_logger.h +++ b/exporters/etw/include/opentelemetry/exporters/etw/etw_logger.h @@ -76,7 +76,7 @@ class Logger : public logs::Logger { static ETWProvider instance; // C++11 magic static return instance; - }; + } /** * @brief Init a reference to etw::ProviderHandle diff --git a/exporters/etw/include/opentelemetry/exporters/etw/etw_properties.h b/exporters/etw/include/opentelemetry/exporters/etw/etw_properties.h index c0f501e866..04ad86130f 100644 --- a/exporters/etw/include/opentelemetry/exporters/etw/etw_properties.h +++ b/exporters/etw/include/opentelemetry/exporters/etw/etw_properties.h @@ -83,7 +83,7 @@ class PropertyValue : public PropertyVariant static std::vector to_vector(const nostd::span &source) { return std::vector(source.begin(), source.end()); - }; + } /** * @brief Convert span to vector @@ -98,7 +98,7 @@ class PropertyValue : public PropertyVariant result.push_back(std::string(item.data())); } return result; - }; + } /** * @brief Convert vector to span. @@ -111,7 +111,7 @@ class PropertyValue : public PropertyVariant { nostd::span result(vec.data(), vec.size()); return result; - }; + } /** * @brief Convert vector to span. @@ -124,7 +124,7 @@ class PropertyValue : public PropertyVariant { nostd::span result(vec.data(), vec.size()); return result; - }; + } public: /** @@ -132,7 +132,7 @@ class PropertyValue : public PropertyVariant * @param v * @return */ - PropertyValue(bool value) : PropertyVariant(value){}; + PropertyValue(bool value) : PropertyVariant(value) {} /** * @brief PropertyValue from integral. @@ -140,7 +140,8 @@ class PropertyValue : public PropertyVariant * @return */ template ::value, bool> = true> - PropertyValue(TInteger number) : PropertyVariant(number){}; + PropertyValue(TInteger number) : PropertyVariant(number) + {} /** * @brief PropertyValue from floating point. @@ -148,14 +149,15 @@ class PropertyValue : public PropertyVariant * @return */ template ::value, bool> = true> - PropertyValue(TFloat number) : PropertyVariant(double(number)){}; + PropertyValue(TFloat number) : PropertyVariant(double(number)) + {} /** * @brief Default PropertyValue (int32_t=0) * @param v * @return */ - PropertyValue() : PropertyVariant(int32_t(0)){}; + PropertyValue() : PropertyVariant(int32_t(0)) {} /** * @brief PropertyValue from array of characters as string. @@ -163,7 +165,7 @@ class PropertyValue : public PropertyVariant * @param v * @return */ - PropertyValue(char value[]) : PropertyVariant(std::string(value)){}; + PropertyValue(char value[]) : PropertyVariant(std::string(value)) {} /** * @brief PropertyValue from array of characters as string. @@ -171,7 +173,7 @@ class PropertyValue : public PropertyVariant * @param v * @return */ - PropertyValue(const char *value) : PropertyVariant(std::string(value)){}; + PropertyValue(const char *value) : PropertyVariant(std::string(value)) {} /** * @brief PropertyValue from string. @@ -179,14 +181,15 @@ class PropertyValue : public PropertyVariant * @param v * @return */ - PropertyValue(const std::string &value) : PropertyVariant(value){}; + PropertyValue(const std::string &value) : PropertyVariant(value) {} /** * @brief PropertyValue from vector as array. * @return */ template - PropertyValue(std::vector value) : PropertyVariant(value){}; + PropertyValue(std::vector value) : PropertyVariant(value) + {} /** * @brief Convert owning PropertyValue to non-owning common::AttributeValue @@ -217,11 +220,11 @@ class PropertyValue : public PropertyVariant case common::AttributeType::kTypeCString: { PropertyVariant::operator=(nostd::get(v)); break; - }; + } case common::AttributeType::kTypeString: { PropertyVariant::operator=(nostd::string_view(nostd::get(v)).data()); break; - }; + } case common::AttributeType::kTypeSpanByte: PropertyVariant::operator=(to_vector(nostd::get>(v))); @@ -361,7 +364,7 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap /** * @brief PropertyValueMap constructor. */ - Properties() : PropertyValueMap(){}; + Properties() : PropertyValueMap() {} /** * @brief PropertyValueMap constructor from initializer list. @@ -369,7 +372,7 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap Properties(const std::initializer_list properties) : PropertyValueMap() { (*this) = (properties); - }; + } /** * @brief PropertyValueMap assignment operator from initializer list. @@ -378,12 +381,12 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap { PropertyValueMap::operator=(properties); return (*this); - }; + } /** * @brief PropertyValueMap constructor from map. */ - Properties(const PropertyValueMap &properties) : PropertyValueMap() { (*this) = properties; }; + Properties(const PropertyValueMap &properties) : PropertyValueMap() { (*this) = properties; } /** * @brief PropertyValueMap assignment operator from map. @@ -392,7 +395,7 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap { PropertyValueMap::operator=(properties); return (*this); - }; + } /** * @brief PropertyValueMap constructor from KeyValueIterable @@ -414,7 +417,7 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap return true; }); return (*this); - }; + } /** * @brief PropertyValueMap property accessor. @@ -439,12 +442,12 @@ class Properties : public common::KeyValueIterable, public PropertyValueMap } } return true; - }; + } /** * @return the number of key-value pairs */ - size_t size() const noexcept override { return PropertyValueMap::size(); }; + size_t size() const noexcept override { return PropertyValueMap::size(); } }; } // namespace etw diff --git a/exporters/etw/include/opentelemetry/exporters/etw/etw_provider.h b/exporters/etw/include/opentelemetry/exporters/etw/etw_provider.h index 616f088187..5b00f05574 100644 --- a/exporters/etw/include/opentelemetry/exporters/etw/etw_provider.h +++ b/exporters/etw/include/opentelemetry/exporters/etw/etw_provider.h @@ -161,8 +161,8 @@ class ETWProvider { data.refCount = 1; data.providerHandle = hProvider; - }; - }; + } + } break; #ifdef HAVE_MSGPACK @@ -180,7 +180,7 @@ class ETWProvider data.refCount = 1; data.providerHandle = hProvider; } - }; + } break; #endif @@ -232,7 +232,7 @@ class ETWProvider } return result; } - }; + } return STATUS_ERROR; } @@ -248,7 +248,7 @@ class ETWProvider { // Provider not registered! return STATUS_ERROR; - }; + } std::string eventName = "NoName"; auto nameField = eventData[ETW_FIELD_NAME]; @@ -361,7 +361,7 @@ class ETWProvider // TODO: unsupported type break; } - }; + } std::vector v = nlohmann::json::to_msgpack(jObj); @@ -385,7 +385,7 @@ class ETWProvider else { writeResponse = EventWrite(providerData.providerHandle, &evtDescriptor, 1, evtData); - }; + } switch (writeResponse) { @@ -401,12 +401,12 @@ class ETWProvider break; default: break; - }; + } if (writeResponse == ERROR_ARITHMETIC_OVERFLOW) { return STATUS_EFBIG; - }; + } return (unsigned long)(writeResponse); #else UNREFERENCED_PARAMETER(providerData); @@ -435,7 +435,7 @@ class ETWProvider { // Provider not registered! return STATUS_ERROR; - }; + } UINT32 eventTags = MICROSOFT_EVENTTAG_NORMAL_PERSISTENCE; @@ -539,7 +539,7 @@ class ETWProvider // TODO: unsupported type break; } - }; + } if (!builder.End()) // Returns false if the metadata is too large. { @@ -572,7 +572,7 @@ class ETWProvider if (writeResponse == HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)) { return STATUS_EFBIG; - }; + } return (unsigned long)(writeResponse); } @@ -598,7 +598,7 @@ class ETWProvider return STATUS_ERROR; } return STATUS_ERROR; - }; + } static const REGHANDLE INVALID_HANDLE = _UI64_MAX; @@ -615,7 +615,7 @@ class ETWProvider { static std::map providers; return providers; - }; + } }; OPENTELEMETRY_END_NAMESPACE diff --git a/exporters/etw/include/opentelemetry/exporters/etw/etw_tracer.h b/exporters/etw/include/opentelemetry/exporters/etw/etw_tracer.h index bad00dde58..cd157f34d5 100644 --- a/exporters/etw/include/opentelemetry/exporters/etw/etw_tracer.h +++ b/exporters/etw/include/opentelemetry/exporters/etw/etw_tracer.h @@ -190,7 +190,7 @@ class Tracer : public trace::Tracer { static ETWProvider instance; // C++11 magic static return instance; - }; + } /** * @brief Internal method that allows to populate Links to other Spans. @@ -219,7 +219,7 @@ class Tracer : public trace::Tracer }); attributes[ETW_FIELD_SPAN_LINKS] = linksValue; } - }; + } /** * @brief Allow our friendly etw::Span to end itself on Tracer. @@ -320,9 +320,9 @@ class Tracer : public trace::Tracer UpdateStatus(currentSpan, evt); etwProvider().write(provHandle, evt, ActivityIdPtr, RelatedActivityIdPtr, 0, encoding); } - }; + } - const trace::TraceId &trace_id() { return traceId_; }; + const trace::TraceId &trace_id() { return traceId_; } friend class Span; @@ -360,7 +360,7 @@ class Tracer : public trace::Tracer nostd::span traceIdBytes( traceIdPtr, traceIdPtr + trace::TraceId::kSize); traceId_ = trace::TraceId(traceIdBytes); - }; + } /** * @brief Start Span @@ -486,10 +486,10 @@ class Tracer : public trace::Tracer // - options.start_steady_time // - options.start_system_time etwProvider().write(provHandle, evt, ActivityIdPtr, RelatedActivityIdPtr, 1, encoding); - }; + } return result; - }; + } /** * @brief Force flush data to Tracer, spending up to given amount of microseconds to flush. @@ -498,7 +498,7 @@ class Tracer : public trace::Tracer * @param timeout Allow Tracer to drop data if timeout is reached * @return */ - void ForceFlushWithMicroseconds(uint64_t) noexcept override{}; + void ForceFlushWithMicroseconds(uint64_t) noexcept override {} /** * @brief Close tracer, spending up to given amount of microseconds to flush and close. @@ -515,7 +515,7 @@ class Tracer : public trace::Tracer { etwProvider().close(provHandle); } - }; + } /** * @brief Add event data to span associated with tracer. @@ -601,7 +601,7 @@ class Tracer : public trace::Tracer #endif etwProvider().write(provHandle, evt, ActivityIdPtr, nullptr, 0, encoding); - }; + } /** * @brief Add event data to span associated with tracer. @@ -615,7 +615,7 @@ class Tracer : public trace::Tracer common::SystemTimestamp timestamp) noexcept { AddEvent(span, name, timestamp, sdk::GetEmptyAttributes()); - }; + } /** * @brief Add event data to span associated with tracer. @@ -625,12 +625,12 @@ class Tracer : public trace::Tracer void AddEvent(trace::Span &span, nostd::string_view name) { AddEvent(span, name, std::chrono::system_clock::now(), sdk::GetEmptyAttributes()); - }; + } /** * @brief Tracer destructor. */ - virtual ~Tracer() { CloseWithMicroseconds(0); }; + virtual ~Tracer() { CloseWithMicroseconds(0); } }; /** @@ -766,7 +766,7 @@ class Span : public trace::Span { name_ = name; UNREFERENCED_PARAMETER(options); - }; + } /** * @brief Span Destructor @@ -840,7 +840,7 @@ class Span : public trace::Span // TODO: not implemented UNREFERENCED_PARAMETER(key); UNREFERENCED_PARAMETER(value); - }; + } /** * @brief Update Span name. @@ -900,7 +900,7 @@ class Span : public trace::Span /// Get Owner tracer of this Span /// /// - trace::Tracer &tracer() const noexcept { return this->owner_; }; + trace::Tracer &tracer() const noexcept { return this->owner_; } }; /** diff --git a/exporters/etw/include/opentelemetry/exporters/etw/uuid.h b/exporters/etw/include/opentelemetry/exporters/etw/uuid.h index ca1a58ac94..a004aec9e3 100644 --- a/exporters/etw/include/opentelemetry/exporters/etw/uuid.h +++ b/exporters/etw/include/opentelemetry/exporters/etw/uuid.h @@ -67,7 +67,7 @@ struct UUID { Data4[i] = 0; } - }; + } /// /// A constructor that creates a UUID object from a hyphenated string as defined by diff --git a/exporters/etw/test/etw_perf_test.cc b/exporters/etw/test/etw_perf_test.cc index d20e3b553c..79052464e8 100644 --- a/exporters/etw/test/etw_perf_test.cc +++ b/exporters/etw/test/etw_perf_test.cc @@ -132,7 +132,7 @@ void BM_AddPropertiesToTracer(benchmark::State &state) while (state.KeepRunning()) { benchmark::DoNotOptimize(provider.AddProperties()); - }; + } provider.Teardown(); } BENCHMARK(BM_AddPropertiesToTracer); @@ -147,7 +147,7 @@ void BM_AddPropertiesStaticToTracer(benchmark::State &state) while (state.KeepRunning()) { benchmark::DoNotOptimize(provider.AddPropertiesStatic()); - }; + } provider.Teardown(); } BENCHMARK(BM_AddPropertiesStaticToTracer); @@ -162,7 +162,7 @@ void BM_AddInitListToTracer(benchmark::State &state) while (state.KeepRunning()) { benchmark::DoNotOptimize(provider.AddInitList()); - }; + } provider.Teardown(); } BENCHMARK(BM_AddInitListToTracer); @@ -178,7 +178,7 @@ void BM_AddMapToTracer(benchmark::State &state) while (state.KeepRunning()) { benchmark::DoNotOptimize(provider.AddMap()); - }; + } provider.Teardown(); } BENCHMARK(BM_AddMapToTracer); diff --git a/exporters/otlp/README.md b/exporters/otlp/README.md index e0b1b7f4bb..9ac6918ba7 100644 --- a/exporters/otlp/README.md +++ b/exporters/otlp/README.md @@ -63,7 +63,7 @@ auto exporter = std::unique_ptr(new otlp::OtlpHttpExport | Option | Env Variable |Default | Description | | ------------ |-----|------------ |------| -| `url` | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317/v1/traces` | The OTLP HTTP endpoint to connect to | +| `url` | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` | The OTLP HTTP endpoint to connect to | | | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | | | | `content_type` | n/a | `application/json` | Data format used - JSON or Binary | | `json_bytes_mapping` | n/a | `JsonBytesMappingKind::kHexId` | Encoding used for trace_id and span_id | diff --git a/exporters/otlp/include/opentelemetry/exporters/otlp/otlp_environment.h b/exporters/otlp/include/opentelemetry/exporters/otlp/otlp_environment.h index c06507daed..4a1882984b 100644 --- a/exporters/otlp/include/opentelemetry/exporters/otlp/otlp_environment.h +++ b/exporters/otlp/include/opentelemetry/exporters/otlp/otlp_environment.h @@ -38,7 +38,7 @@ inline const std::string GetOtlpDefaultHttpEndpoint() { constexpr char kOtlpTracesEndpointEnv[] = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"; constexpr char kOtlpEndpointEnv[] = "OTEL_EXPORTER_OTLP_ENDPOINT"; - constexpr char kOtlpEndpointDefault[] = "http://localhost:4317/v1/traces"; + constexpr char kOtlpEndpointDefault[] = "http://localhost:4318/v1/traces"; auto endpoint = opentelemetry::sdk::common::GetEnvironmentVariable(kOtlpTracesEndpointEnv); if (endpoint.empty())