Merge branch 'main' into patch-1

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,32 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [main]
+
+jobs:
+  CodeQL-Build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2.3.4
+      with:
+         submodules: 'recursive'
+    - name: Remove Third_party Modules from Code Scan
+      run: |
+        rm -rf third_party
+    - name: Setup
+      run: |
+        sudo ./ci/setup_cmake.sh
+        sudo ./ci/setup_ci_environment.sh
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+       languages: cpp
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

CHANGELOG.md

@@ -15,6 +15,7 @@ Increment the:
 
 ## [Unreleased]
 
+* [CI] Add CodeQL security scan CI workflow ([#770](https://github.com/open-telemetry/opentelemetry-cpp/pull/770))
 * [EXPORTER] Populate resource to OTLP proto data ([#758](https://github.com/open-telemetry/opentelemetry-cpp/pull/758))
 
 ## [0.6.0] 2021-05-11

CMakeLists.txt

@@ -65,9 +65,17 @@ if(WITH_STL)
 
   # Optimize for speed to reduce the hops
   if(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
-    set(CMAKE_CXX_FLAGS_SPEED "/O2")
+    if(CMAKE_BUILD_TYPE MATCHES Debug)
+      # Turn off optimizations for DEBUG
+      set(MSVC_CXX_OPT_FLAG "/Od")
+    else()
+      string(REGEX MATCH "\/O" result ${CMAKE_CXX_FLAGS})
+      if(NOT ${result} MATCHES "\/O")
+        set(MSVC_CXX_OPT_FLAG "/O2")
+      endif()
+    endif()
     set(CMAKE_CXX_FLAGS
-        "${CMAKE_CXX_FLAGS} /Zc:__cplusplus ${CMAKE_CXX_FLAGS_SPEED}")
+        "${CMAKE_CXX_FLAGS} /Zc:__cplusplus ${MSVC_CXX_OPT_FLAG}")
   endif()
 endif()
 
@@ -84,12 +92,22 @@ option(WITH_JAEGER "Whether to include the Jaeger exporter" OFF)
 
 option(BUILD_TESTING "Whether to enable tests" ON)
 if(WIN32)
+  if(BUILD_TESTING)
+    if(MSVC)
+      # GTest bug: https://github.com/google/googletest/issues/860
+      add_compile_options(/wd4275)
+    endif()
+  endif()
   option(WITH_ETW "Whether to include the ETW Exporter in the SDK" ON)
   if(WITH_ETW)
     add_definitions(-DHAVE_MSGPACK)
   endif(WITH_ETW)
 endif(WIN32)
 
+option(
+  WITH_API_ONLY
+  "Only build the API (use as a header-only library). Overrides WITH_EXAMPLES"
+  OFF)
 option(WITH_EXAMPLES "Whether to build examples" ON)
 
 option(WITH_METRICS_PREVIEW "Whether to build metrics preview" OFF)
@@ -206,17 +224,21 @@ endif()
 include(CMakePackageConfigHelpers)
 
 include_directories(api/include)
-include_directories(sdk/include)
-include_directories(sdk)
-include_directories(ext/include)
 
 add_subdirectory(api)
-add_subdirectory(sdk)
-add_subdirectory(exporters)
-if(WITH_EXAMPLES)
-  add_subdirectory(examples)
+
+if(NOT WITH_API_ONLY)
+  include_directories(sdk/include)
+  include_directories(sdk)
+  include_directories(ext/include)
+
+  add_subdirectory(sdk)
+  add_subdirectory(exporters)
+  if(WITH_EXAMPLES)
+    add_subdirectory(examples)
+  endif()
+  add_subdirectory(ext)
 endif()
-add_subdirectory(ext)
 
 # Add nlohmann/json submodule to include directories
 include_directories(third_party/nlohmann-json/single_include)

docs/building-with-vs2019.md

@@ -0,0 +1,189 @@
+# Building OpenTelemetry C++ SDK with Visual Studio 2019, CMake and Ninja
+
+## Preface
+
+These instructions are focused on developers and integrators, providing a hassle-free
+and FAST option of building OpenTelemetry C++ SDK with Visual Studio on Windows.
+
+The process is optimized for both scenarios:
+
+- SDK developer experience on developer machine.
+- final product CI/CD pipeline.
+
+## Build System Components
+
+Visual Studio 2019 is a Full-featured integrated development environment (IDE) for
+Android, iOS, Windows, web, and cloud. There are three editions:
+
+- FREE [Community Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16)
+- [Professional Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Professional&rel=16)
+- [Enterprise Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Enterprise&rel=16)
+
+There is also no-IDE 'headless' set of command line tools available as
+`Visual Studio 2019 Build Tools` package. You may install it on Windows
+via [Chocolatey package manager](https://community.chocolatey.org/packages/visualstudio2019buildtools).
+
+You may also use Visual Studio with Windows 10 Subsystem for Linux to cross-compile
+the SDK [targeting Linux distributions](https://code.visualstudio.com/docs/cpp/config-wsl).
+Linux build process is largely identical to Windows process described below,
+with `tools/setup-buildtools.sh` and `tools/build.sh` running on Linux.
+
+Older versions of Visual Studio, such as 2015 and 2017 are known to work well
+with CMake and Ninja. However, these old versions are not covered by instructions
+below. If you would like to contribute additional instructions for older versions,
+feel free to contribute a Pull Request detailing your build experience with older
+versions.
+
+[CMake](https://cmake.org/) is cross-platform free and open-source software for
+build automation, testing, packaging and installation of software by using a
+compiler-independent method. CMake is not a build system but rather it generates
+another system's build files.
+
+[MSBuild](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019)
+is a default build system used by Visual Studio for loading and building software
+projects.
+
+[Ninja](https://ninja-build.org/) is a small build system with a focus on speed.
+It differs from other build systems in two major respects: it is designed to have
+its input files generated by a higher-level build system, and it is designed
+to run builds as fast as possible.
+
+[Chocolatey package manager](https://chocolatey.org/) has the largest online registry
+of Windows packages. Chocolatey packages encapsulate everything required to manage
+a particular piece of software into one deployment artifact by wrapping installers,
+executables, zips, and/or scripts into a compiled package file.
+
+[vcpkg](https://vcpkg.io/en/index.html) is a free C/C++ package manager for acquiring
+and managing libraries. Choose from over 1500 open source libraries to download
+and build in a single step or add your own private libraries to simplify your
+build process. Maintained by the Microsoft C++ team and open source contributors.
+
+## Installing Prerequisites
+
+Please install the following software:
+
+- Install Visual Studio 2019 with C/C++ development tools, including CMake tools.
+[This article](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160)
+ explains the fundamentals of working with CMake projects in Visual Studio.
+
+- Install [Git tools for Windows](https://git-scm.com/downloads).
+
+Setup script below uses Chocolatey to install the following components:
+
+- `vswhere` - utility to auto-discover Visual Studio installation.
+- `cmake`
+- `git`
+- `vcpkg` to download, compile and install 3rd party C++ libraries from source.
+
+List of C++ dependencies compiled and installed via `vcpkg`:
+
+- [Google Test](https://github.com/google/googletest)
+- [Google Benchmark](https://github.com/google/benchmark)
+- [Microsoft GSL](https://github.com/microsoft/GSL)
+- [nlohmann/json](https://github.com/nlohmann/json)
+- [Abseil](https://github.com/abseil/abseil-cpp)
+- [Protocol Buffers](https://github.com/protocolbuffers/protobuf)
+- [gRPC](https://github.com/grpc/grpc)
+- [Prometheus C++ client](https://github.com/jupp0r/prometheus-cpp)
+- [cURL](https://github.com/curl/curl)
+
+## Command Line Build Process
+
+Start `Command Prompt` as Administrator and execute the following commands:
+
+```console
+git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp
+cd opentelemetry-cpp
+tools\setup-buildtools.cmd
+tools\build.cmd
+```
+
+Let's dissect the flow:
+
+```console
+git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp
+```
+
+SDK will be cloned recursively with remote submodule dependencies.
+
+```console
+cd opentelemetry-cpp
+tools\setup-buildtools.cmd
+```
+
+The necessary build tools are installed. This step requires elevation to install
+additional tooling, e.g. CMake to `Program Files`. The necessary dependencies are
+being built using [vcpkg package manager](https://vcpkg.io/en/index.html). This
+one-time step is time-consuming - about up to 5-10 minutes. It has to be done once
+during the initial installation and configuration of build tools and dependencies.
+
+```console
+tools\build.cmd
+```
+
+The build of all SDK components is done using CMake + ninja in less than couple
+minutes. Above script shows you how to build both configurations:
+
+- `nostd`  - OpenTelemetry implementation of standard containers.
+- `stdlib` - Standard Template Library containers.
+
+You may execute this workflow in a docker container. Please refer to generic
+instructions that detail how to [run build build tools in a docker container](https://docs.microsoft.com/en-us/visualstudio/install/build-tools-container?view=vs-2019).
+
+## Building in Visual Studio 2019 IDE
+
+- Run as Administrator: `tools\setup-buildtools.cmd` to install the necessary
+build tooling. This script installs all build tools and builds all 3rd party
+dependencies from source using [vcpkg package manager](https://vcpkg.io/en/index.html).
+- Launch Visual Studio 2019 IDE.
+- Use `Open a local folder` option to open the folder where you cloned the source code.
+- Right-click on `CMakeLists.txt` and choose `Generate Cache for opentelemetry-cpp`.
+- In the top bar menu - select `Build -> Build All` to build SDK, Exporters and Tests.
+- You can use [Google Test Adapter](https://marketplace.visualstudio.com/items?itemName=ChristianSoltenborn.GoogleTestAdapter)
+Visual Studio extension to run all SDK and Exporter tests in IDE.
+- You can individually select and run only given tests or examples.
+
+Visual Studio provides an excellent debugging and troubleshooting experience,
+with incremental builds using Ninja typically taking just one click to build
+and less than a few seconds for the build to complete.
+
+## Build time comparison between `MSBuild` and `Ninja`
+
+After the initial set of 3rd party dependencies have been built via
+`tools\setup-buildtools.cmd`, we can benchmark the OpenTelemetry C++ SDK build
+times with [MSBuild](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019)
+vs with [Ninja](https://ninja-build.org/).
+
+[ptime utility](https://community.chocolatey.org/packages/ptime) may be used
+to measure the total execution time for two build configurations built in one
+run: `nostd-debug` and `stdlib-debug`.
+
+### MSBuild build timing
+
+```console
+set CMAKE_GEN=Visual Studio 16 2019
+ptime build.cmd
+...
+Execution time: 543.701 s
+```
+
+### Ninja build timing
+
+```console
+REM Unset CMAKE_GEN= - default is ninja with autodetection of ninja.exe tool path
+set CMAKE_GEN=
+ptime build.cmd
+...
+Execution time: 105.158 s
+```
+
+## Conclusion
+
+It is strongly recommended to build the SDK with *Ninja* since it is at least x5
+times faster than MSBuild for a full clean build. Incremental builds with *Ninja*
+are also considerably faster. Each incremental build is taking about 10 seconds
+total for 2 build configurations. Absolute time may differ depending on machine
+being benchmarked. Relative ratio on most machines demonstrates that building
+with *Ninja* build system greatly optimizes your development cycle. Not only it
+saves your development time, optimizes your CI/CD cycle, but it is also much more
+environmentally friendly.