Skip to content

Commit

Permalink
Merge branch 'main' into switch-grpchttp-port
Browse files Browse the repository at this point in the history
  • Loading branch information
ThomsonTan authored Oct 19, 2021
2 parents 422f73e + 096c08b commit cd3f475
Show file tree
Hide file tree
Showing 16 changed files with 683 additions and 270 deletions.
53 changes: 19 additions & 34 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:/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).
Expand Down Expand Up @@ -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:/open-telemetry/opentelemetry-specification).

It's especially valuable to read through the [library
guidelines](https:/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
Expand All @@ -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:/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:/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:/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:/open-telemetry/opentelemetry-cpp/pull/94).

* Read through the [Java Quick-Start
Guide](https:/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:/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:/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.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/public/api/api.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Opentelmetry C++ API
OpenTelemetry C++ API
====================

.. toctree::
Expand Down
9 changes: 9 additions & 0 deletions exporters/etw/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ install(
if(BUILD_TESTING)
add_executable(etw_provider_test test/etw_provider_test.cc)
add_executable(etw_tracer_test test/etw_tracer_test.cc)
add_executable(etw_logger_test test/etw_logger_test.cc)

add_executable(etw_perf_test test/etw_perf_test.cc)

target_link_libraries(etw_provider_test ${GTEST_BOTH_LIBRARIES}
Expand All @@ -35,6 +37,9 @@ if(BUILD_TESTING)
target_link_libraries(etw_tracer_test ${GTEST_BOTH_LIBRARIES}
opentelemetry_exporter_etw ${CMAKE_THREAD_LIBS_INIT})

target_link_libraries(etw_logger_test ${GTEST_BOTH_LIBRARIES}
opentelemetry_exporter_etw ${CMAKE_THREAD_LIBS_INIT})

target_link_libraries(
etw_perf_test benchmark::benchmark ${GTEST_BOTH_LIBRARIES}
opentelemetry_exporter_etw ${CMAKE_THREAD_LIBS_INIT})
Expand All @@ -47,5 +52,9 @@ if(BUILD_TESTING)
TARGET etw_tracer_test
TEST_PREFIX exporter.
TEST_LIST etw_tracer_test)
gtest_add_tests(
TARGET etw_logger_test
TEST_PREFIX exporter.
TEST_LIST etw_logger_test)

endif() # BUILD_TESTING
186 changes: 186 additions & 0 deletions exporters/etw/include/opentelemetry/exporters/etw/etw_config.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

#pragma once
#include <map>

#include "opentelemetry/nostd/shared_ptr.h"
#include "opentelemetry/nostd/string_view.h"
#include "opentelemetry/nostd/unique_ptr.h"
#include "opentelemetry/nostd/variant.h"
#include "opentelemetry/trace/span_id.h"

#include "opentelemetry/exporters/etw/etw_provider.h"

OPENTELEMETRY_BEGIN_NAMESPACE
namespace exporter
{
namespace etw
{
/**
* @brief TelemetryProvider Options passed via SDK API.
*/
using TelemetryProviderOptions =
std::map<std::string, nostd::variant<std::string, uint64_t, float, bool>>;

/**
* @brief TelemetryProvider runtime configuration class. Internal representation
* of TelemetryProviderOptions used by various components of SDK.
*/
typedef struct
{
bool enableTraceId; // Set `TraceId` on ETW events
bool enableSpanId; // Set `SpanId` on ETW events
bool enableActivityId; // Assign `SpanId` to `ActivityId`
bool enableActivityTracking; // Emit TraceLogging events for Span/Start and Span/Stop Not used
// for Logs
bool enableRelatedActivityId; // Assign parent `SpanId` to `RelatedActivityId`
bool enableAutoParent; // Start new spans as children of current active span, Not used for Logs
ETWProvider::EventFormat
encoding; // Event encoding to use for this provider (TLD, MsgPack, XML, etc.).
} TelemetryProviderConfiguration;

/**
* @brief Helper template to convert a variant value from TelemetryProviderOptions to
* LoggerProviderConfiguration
*
* @param options TelemetryProviderOptions passed on API surface
* @param key Option name
* @param value Reference to destination value
* @param defaultValue Default value if option is not supplied
*/
template <typename T>
static inline void GetOption(const TelemetryProviderOptions &options,
const char *key,
T &value,
T defaultValue)
{
auto it = options.find(key);
if (it != options.end())
{
auto val = it->second;
value = nostd::get<T>(val);
}
else
{
value = defaultValue;
}
}

/**
* @brief Helper template to convert encoding config option to EventFormat.
* Configuration option passed as `options["encoding"] = "MsgPack"`.
* Default encoding is TraceLogging Dynamic Manifest (TLD).
*
* Valid encoding names listed below.
*
* For MessagePack encoding:
* - "MSGPACK"
* - "MsgPack"
* - "MessagePack"
*
* For XML encoding:
* - "XML"
* - "xml"
*
* For TraceLogging Dynamic encoding:
* - "TLD"
* - "tld"
*
*/
static inline ETWProvider::EventFormat GetEncoding(const TelemetryProviderOptions &options)
{
ETWProvider::EventFormat evtFmt = ETWProvider::EventFormat::ETW_MANIFEST;

auto it = options.find("encoding");
if (it != options.end())
{
auto varValue = it->second;
std::string val = nostd::get<std::string>(varValue);

#pragma warning(push)
#pragma warning(disable : 4307) /* Integral constant overflow - OK while computing hash */
auto h = utils::hashCode(val.c_str());
switch (h)
{
case CONST_HASHCODE(MSGPACK):
// nobrk
case CONST_HASHCODE(MsgPack):
// nobrk
case CONST_HASHCODE(MessagePack):
evtFmt = ETWProvider::EventFormat::ETW_MSGPACK;
break;

case CONST_HASHCODE(XML):
// nobrk
case CONST_HASHCODE(xml):
evtFmt = ETWProvider::EventFormat::ETW_XML;
break;

case CONST_HASHCODE(TLD):
// nobrk
case CONST_HASHCODE(tld):
// nobrk
evtFmt = ETWProvider::EventFormat::ETW_MANIFEST;
break;

default:
break;
}
#pragma warning(pop)
}

return evtFmt;
}

/**
* @brief Utility template to obtain etw::TracerProvider._config or etw::LoggerProvider._config
*
* @tparam T etw::TracerProvider
* @param t etw::TracerProvider ref
* @return TelemetryProviderConfiguration ref
*/
template <class T>
TelemetryProviderConfiguration &GetConfiguration(T &t)
{
return t.config_;
}

/**
* @brief Utility template to convert SpanId or TraceId to hex.
* @param id - value of SpanId or TraceId
* @return Hexadecimal representation of Id as string.
*/
template <class T>
static inline std::string ToLowerBase16(const T &id)
{
char buf[2 * T::kSize] = {0};
id.ToLowerBase16(buf);
return std::string(buf, sizeof(buf));
}

/**
* @brief Utility method to convert span_id (8 byte) to ActivityId GUID (16 bytes)
* @param span OpenTelemetry Span Id object
* @return GUID struct containing 8-bytes of SpanId + 8 NUL bytes.
*/
static inline bool CopySpanIdToActivityId(const opentelemetry::trace::SpanId &span_id,
GUID &outGuid)
{
memset(&outGuid, 0, sizeof(outGuid));
if (!span_id.IsValid())
{
return false;
}
auto spanId = span_id.Id().data();
uint8_t *guidPtr = reinterpret_cast<uint8_t *>(&outGuid);
for (size_t i = 0; i < 8; i++)
{
guidPtr[i] = spanId[i];
}
return true;
}

} // namespace etw
} // namespace exporter
OPENTELEMETRY_END_NAMESPACE
10 changes: 10 additions & 0 deletions exporters/etw/include/opentelemetry/exporters/etw/etw_fields.h
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,22 @@
# define ETW_FIELD_STATUSCODE "StatusCode" /* Span status code */
# define ETW_FIELD_STATUSMESSAGE "StatusMessage" /* Span status message */
# define ETW_FIELD_SUCCESS "Success" /* Span success */
# define ETW_FIELD_TIMESTAMP "Timestamp" /* Log timestamp */

/* Value constants */
# define ETW_VALUE_SPAN "Span" /* ETW event name for Span */
# define ETW_VALUE_LOG "Log" /* ETW event name for Log */

# define ETW_VALUE_SPAN_START "SpanStart" /* ETW for Span Start */
# define ETW_VALUE_SPAN_END "SpanEnd" /* ETW for Span Start */


/* Log specific */
# define ETW_FIELD_LOG_BODY "body" /* Log body */
# define ETW_FIELD_LOG_SEVERITY_TEXT "severityText" /* Sev text */
# define ETW_FIELD_LOG_SEVERITY_NUM "severityNumber" /* Sev num */


#endif

/* clang-format on */
Loading

0 comments on commit cd3f475

Please sign in to comment.