Add TraceId class. (open-telemetry#31)

api/include/opentelemetry/trace/trace_id.h

@@ -0,0 +1,83 @@
+// Copyright 2020, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+
+#include "opentelemetry/nostd/span.h"
+
+namespace opentelemetry
+{
+namespace trace
+{
+
+// TraceId represents an opaque 128-bit trace identifier. The trace identifier
+// remains constant across the trace. A valid trace identifier is a 16-byte array with at
+// least one non-zero byte.
+class TraceId final
+{
+public:
+  // The size in bytes of the TraceId.
+  static constexpr int kSize = 16;
+
+  // An invalid TraceId (all zeros).
+  TraceId() noexcept : rep_{0} {}
+
+  // Creates a TraceId with the given ID.
+  explicit TraceId(nostd::span<const uint8_t, kSize> id) noexcept
+  {
+    memcpy(rep_, id.data(), kSize);
+  }
+
+  // Populates the buffer with the lowercase base16 representation of the ID.
+  void ToLowerBase16(nostd::span<char, 2 * kSize> buffer) const noexcept
+  {
+    constexpr char kHex[] = "0123456789ABCDEF";
+    for (int i = 0; i < kSize; ++i)
+    {
+      buffer[i * 2 + 0] = kHex[(rep_[i] >> 4) & 0xF];
+      buffer[i * 2 + 1] = kHex[(rep_[i] >> 0) & 0xF];
+    }
+  }
+
+  // Returns a nostd::span of the ID.
+  nostd::span<const uint8_t, kSize> Id() const noexcept
+  {
+    return nostd::span<const uint8_t, kSize>(rep_);
+  }
+
+  bool operator==(const TraceId &that) const noexcept
+  {
+    return memcmp(rep_, that.rep_, kSize) == 0;
+  }
+
+  bool operator!=(const TraceId &that) const noexcept { return !(*this == that); }
+
+  // Returns false if the TraceId is all zeros.
+  bool IsValid() const noexcept { return *this != TraceId(); }
+
+  // Copies the opaque TraceId data to dest.
+  void CopyBytesTo(nostd::span<uint8_t, kSize> dest) const noexcept
+  {
+    memcpy(dest.data(), rep_, kSize);
+  }
+
+private:
+  uint8_t rep_[kSize];
+};
+
+}  // namespace trace
+}  // namespace opentelemetry

api/test/trace/BUILD

@@ -19,3 +19,14 @@ cc_test(
         "@com_google_googletest//:gtest_main",
     ],
 )
+
+cc_test(
+    name = "trace_id_test",
+    srcs = [
+        "trace_id_test.cc",
+    ],
+    deps = [
+        "//api",
+        "@com_google_googletest//:gtest_main",
+    ],
+)

api/test/trace/CMakeLists.txt

@@ -9,3 +9,8 @@ add_executable(span_id_test span_id_test.cc)
 target_link_libraries(span_id_test ${GTEST_BOTH_LIBRARIES}
                       ${CMAKE_THREAD_LIBS_INIT} opentelemetry_api)
 gtest_add_tests(TARGET span_id_test TEST_PREFIX trace. TEST_LIST span_id_test)
+
+add_executable(trace_id_test trace_id_test.cc)
+target_link_libraries(trace_id_test ${GTEST_BOTH_LIBRARIES}
+                      ${CMAKE_THREAD_LIBS_INIT} opentelemetry_api)
+gtest_add_tests(TARGET trace_id_test TEST_PREFIX trace. TEST_LIST trace_id_test)

api/test/trace/trace_id_test.cc

@@ -0,0 +1,45 @@
+#include "opentelemetry/trace/trace_id.h"
+
+#include <cstring>
+#include <string>
+
+#include <gtest/gtest.h>
+
+namespace
+{
+
+using opentelemetry::trace::TraceId;
+
+std::string Hex(const opentelemetry::trace::TraceId &trace)
+{
+  char buf[32];
+  trace.ToLowerBase16(buf);
+  return std::string(buf, sizeof(buf));
+}
+
+TEST(TraceIdTest, DefaultConstruction)
+{
+  TraceId id;
+  EXPECT_FALSE(id.IsValid());
+  EXPECT_EQ("00000000000000000000000000000000", Hex(id));
+}
+
+TEST(TraceIdTest, ValidId)
+{
+  constexpr uint8_t buf[] = {1, 2, 3, 4, 5, 6, 7, 8, 8, 7, 6, 5, 4, 3, 2, 1};
+  TraceId id(buf);
+  EXPECT_TRUE(id.IsValid());
+  EXPECT_EQ("01020304050607080807060504030201", Hex(id));
+  EXPECT_NE(TraceId(), id);
+  EXPECT_EQ(TraceId(buf), id);
+}
+
+TEST(TraceIdTest, CopyBytesTo)
+{
+  constexpr uint8_t src[] = {1, 2, 3, 4, 5, 6, 7, 8, 8, 7, 6, 5, 4, 3, 2, 1};
+  TraceId id(src);
+  uint8_t buf[TraceId::kSize];
+  id.CopyBytesTo(buf);
+  EXPECT_TRUE(memcmp(src, buf, sizeof(buf)) == 0);
+}
+}  // namespace