[EXPORTER] Add a JsonWriter interface for OTLP/JSON serialization

CHANGELOG.md

@@ -15,6 +15,11 @@ Increment the:
 
 ## [Unreleased]
 
+* [EXPORTER] Add a `JsonWriter` interface for OTLP/JSON serialization, so a
+  consumer can supply their own JSON backend in place of the default
+  nlohmann-json one.
+  [#4556](https://github.com/open-telemetry/opentelemetry-cpp/pull/4556)
+
 ## [1.30.0] 2026-10-22
 
 This release contains:

CMakeLists.txt

@@ -351,6 +351,17 @@ otelcpp_dependent_option(
   "OTELCPP_WITH_OTLP_HTTP OR OTELCPP_WITH_ELASTICSEARCH OR OTELCPP_WITH_ZIPKIN OR OTELCPP_BUILD_W3CTRACECONTEXT_TEST OR OTELCPP_WITH_EXAMPLES_HTTP"
   OFF)
 
+#
+# Do we need the NLOHMANN JSON WRITER ?
+#
+
+otelcpp_dependent_option(
+  OTELCPP_WITH_JSON_WRITER_NLOHMANN
+  "Use the nlohmann-json JsonWriter backend. Defaults to ON when an OTLP exporter that emits JSON is enabled; set OFF to supply a custom JsonWriterFactory."
+  ON
+  "OTELCPP_WITH_OTLP_HTTP OR OTELCPP_WITH_OTLP_FILE"
+  OFF)
+
 #
 # Locally override options if OTELCPP_WITH_API_ONLY is set to prevent third
 # party dependencies from being imported
@@ -369,6 +380,7 @@ if(OTELCPP_WITH_API_ONLY)
   otelcpp_set_option(OTELCPP_WITH_ETW OFF)
   otelcpp_set_option(OTELCPP_WITH_CONFIGURATION OFF)
   otelcpp_set_option(OTELCPP_WITH_HTTP_CLIENT_CURL OFF)
+  otelcpp_set_option(OTELCPP_WITH_JSON_WRITER_NLOHMANN OFF)
   otelcpp_set_option(OTELCPP_WITH_OTLP_HTTP_COMPRESSION OFF)
   otelcpp_set_option(OTELCPP_WITH_BENCHMARK OFF)
   otelcpp_set_option(OTELCPP_WITH_FUNC_TESTS OFF)
@@ -425,8 +437,7 @@ endif()
 
 if(OTELCPP_WITH_ELASTICSEARCH
    OR OTELCPP_WITH_ZIPKIN
-   OR OTELCPP_WITH_OTLP_HTTP
-   OR OTELCPP_WITH_OTLP_FILE
+   OR OTELCPP_WITH_JSON_WRITER_NLOHMANN
    OR OTELCPP_BUILD_W3CTRACECONTEXT_TEST
    OR OTELCPP_WITH_ETW)
   set(USE_NLOHMANN_JSON ON)
@@ -603,6 +614,9 @@ message(STATUS "OTELCPP_WITH_OTLP_HTTP: ${OTELCPP_WITH_OTLP_HTTP}")
 message(STATUS "OTELCPP_WITH_OTLP_FILE: ${OTELCPP_WITH_OTLP_FILE}")
 message(
   STATUS "OTELCPP_WITH_HTTP_CLIENT_CURL: ${OTELCPP_WITH_HTTP_CLIENT_CURL}")
+message(
+  STATUS
+    "OTELCPP_WITH_JSON_WRITER_NLOHMANN: ${OTELCPP_WITH_JSON_WRITER_NLOHMANN}")
 message(STATUS "OTELCPP_WITH_ZIPKIN: ${OTELCPP_WITH_ZIPKIN}")
 message(STATUS "OTELCPP_WITH_PROMETHEUS: ${OTELCPP_WITH_PROMETHEUS}")
 message(STATUS "OTELCPP_WITH_ELASTICSEARCH: ${OTELCPP_WITH_ELASTICSEARCH}")

ci/verify_packages.sh

@@ -27,6 +27,9 @@ done
 # OTLP exporters
 validate_package "opentelemetry_otlp_recordable"
 validate_package "opentelemetry_exporter_otlp_builder_utils"
+for variant in json_writer json_writer_nlohmann json_converter; do
+  validate_package "opentelemetry_exporter_otlp_${variant}"
+done
 
 # OTLP gRPC exporter
 validate_package "opentelemetry_exporter_otlp_grpc"

exporters/otlp/BUILD

@@ -71,6 +71,71 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "otlp_json_writer",
+    srcs = select({
+        ":json_writer_nlohmann_enabled": ["src/otlp_json_writer_nlohmann.cc"],
+        "//conditions:default": [],
+    }),
+    hdrs = [
+        "include/opentelemetry/exporters/otlp/detail/default_json_writer_factory.h",
+        "include/opentelemetry/exporters/otlp/otlp_json_writer.h",
+        "include/opentelemetry/exporters/otlp/otlp_json_writer_factory.h",
+    ] + select({
+        ":json_writer_nlohmann_enabled": [
+            "include/opentelemetry/exporters/otlp/otlp_json_writer_factory_nlohmann.h",
+        ],
+        "//conditions:default": [],
+    }),
+    defines = select({
+        ":json_writer_nlohmann_enabled": ["ENABLE_JSON_WRITER_NLOHMANN"],
+        "//conditions:default": [],
+    }),
+    strip_include_prefix = "include",
+    tags = ["otlp"],
+    deps = [
+        "//api",
+        "//sdk/src/common:base64",
+        "//sdk/src/common:global_log_handler",
+    ] + select({
+        ":json_writer_nlohmann_enabled": ["@github_nlohmann_json//:json"],
+        "//conditions:default": [],
+    }),
+)
+
+config_setting(
+    name = "json_writer_nlohmann_enabled",
+    flag_values = {
+        ":with_json_writer_nlohmann": "true",
+    },
+)
+
+bool_flag(
+    name = "with_json_writer_nlohmann",
+    build_setting_default = True,
+)
+
+cc_library(
+    name = "otlp_json_converter",
+    srcs = [
+        "src/otlp_json_converter.cc",
+    ],
+    hdrs = [
+        "include/opentelemetry/exporters/otlp/otlp_http.h",
+        "include/opentelemetry/exporters/otlp/otlp_json_converter.h",
+        "include/opentelemetry/exporters/otlp/protobuf_include_prefix.h",
+        "include/opentelemetry/exporters/otlp/protobuf_include_suffix.h",
+    ],
+    strip_include_prefix = "include",
+    tags = ["otlp"],
+    deps = [
+        ":otlp_json_writer",
+        "//api",
+        "//sdk/src/common:base64",
+        "@com_google_protobuf//:protobuf",
+    ],
+)
+
 cc_library(
     name = "otlp_builder_utils",
     srcs = [
@@ -224,14 +289,15 @@ cc_library(
         "otlp_http_log",
     ],
     deps = [
+        ":otlp_json_converter",
+        ":otlp_json_writer",
         "//api",
         "//ext/src/http/client/curl:http_client_curl",
         "//sdk:headers",
         "//sdk/src/common:base64",
         "@com_github_opentelemetry_proto//:common_proto_cc",
         "@com_google_absl//absl/strings",
         "@com_google_protobuf//:protobuf",
-        "@github_nlohmann_json//:json",
     ],
 )
 
@@ -305,12 +371,13 @@ cc_library(
         "otlp_file",
     ],
     deps = [
+        ":otlp_json_converter",
+        ":otlp_json_writer",
         "//api",
         "//sdk:headers",
         "//sdk/src/common:base64",
         "@com_github_opentelemetry_proto//:common_proto_cc",
         "@com_google_absl//absl/strings",
-        "@github_nlohmann_json//:json",
     ],
 )
 
@@ -673,6 +740,44 @@ cc_library(
     ],
 )
 
+cc_test(
+    name = "otlp_json_converter_test",
+    srcs = [
+        "test/otlp_json_converter_test.cc",
+        "test/otlp_stub_json_writer.h",
+    ],
+    tags = [
+        "otlp",
+        "test",
+    ],
+    deps = [
+        ":otlp_json_converter",
+        "@com_github_opentelemetry_proto//:common_proto_cc",
+        "@com_github_opentelemetry_proto//:metrics_service_proto_cc",
+        "@com_github_opentelemetry_proto//:trace_service_proto_cc",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "otlp_json_writer_nlohmann_test",
+    srcs = [
+        "test/otlp_json_writer_contract_test.cc",
+        "test/otlp_json_writer_contract_test.h",
+        "test/otlp_json_writer_nlohmann_test.cc",
+    ],
+    tags = [
+        "otlp",
+        "test",
+    ],
+    deps = [
+        ":otlp_json_writer",
+        "//sdk/src/common:global_log_handler",
+        "//test_common:headers",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
 cc_test(
     name = "otlp_recordable_test",
     srcs = ["test/otlp_recordable_test.cc"],
@@ -724,7 +829,10 @@ cc_test(
 
 cc_test(
     name = "otlp_file_client_test",
-    srcs = ["test/otlp_file_client_test.cc"],
+    srcs = [
+        "test/otlp_file_client_test.cc",
+        "test/otlp_stub_json_writer.h",
+    ],
     tags = [
         "otlp",
         "otlp_file",
@@ -789,7 +897,10 @@ cc_test(
 
 cc_test(
     name = "otlp_http_exporter_test",
-    srcs = ["test/otlp_http_exporter_test.cc"],
+    srcs = [
+        "test/otlp_http_exporter_test.cc",
+        "test/otlp_http_request_body_capture.h",
+    ],
     tags = [
         "otlp",
         "otlp_http",
@@ -839,7 +950,10 @@ cc_test(
 
 cc_test(
     name = "otlp_file_exporter_factory_test",
-    srcs = ["test/otlp_file_exporter_factory_test.cc"],
+    srcs = [
+        "test/otlp_file_exporter_factory_test.cc",
+        "test/otlp_stub_json_writer.h",
+    ],
     tags = [
         "otlp",
         "otlp_file",
@@ -855,7 +969,10 @@ cc_test(
 
 cc_test(
     name = "otlp_http_log_record_exporter_test",
-    srcs = ["test/otlp_http_log_record_exporter_test.cc"],
+    srcs = [
+        "test/otlp_http_log_record_exporter_test.cc",
+        "test/otlp_http_request_body_capture.h",
+    ],
     tags = [
         "otlp",
         "otlp_http_log",
@@ -905,7 +1022,10 @@ cc_test(
 
 cc_test(
     name = "otlp_file_log_record_exporter_factory_test",
-    srcs = ["test/otlp_file_log_record_exporter_factory_test.cc"],
+    srcs = [
+        "test/otlp_file_log_record_exporter_factory_test.cc",
+        "test/otlp_stub_json_writer.h",
+    ],
     tags = [
         "otlp",
         "otlp_file_log",
@@ -989,7 +1109,10 @@ cc_test(
 
 cc_test(
     name = "otlp_http_metric_exporter_test",
-    srcs = ["test/otlp_http_metric_exporter_test.cc"],
+    srcs = [
+        "test/otlp_http_metric_exporter_test.cc",
+        "test/otlp_http_request_body_capture.h",
+    ],
     tags = [
         "otlp",
         "otlp_http_metric",
@@ -1036,7 +1159,10 @@ cc_test(
 
 cc_test(
     name = "otlp_file_metric_exporter_factory_test",
-    srcs = ["test/otlp_file_metric_exporter_factory_test.cc"],
+    srcs = [
+        "test/otlp_file_metric_exporter_factory_test.cc",
+        "test/otlp_stub_json_writer.h",
+    ],
     tags = [
         "otlp",
         "otlp_file_metric",
@@ -1049,6 +1175,66 @@ cc_test(
     ],
 )
 
+cc_test(
+    name = "otlp_file_exporter_default_json_writer_test",
+    srcs = ["test/otlp_file_exporter_default_json_writer_test.cc"],
+    tags = [
+        "otlp",
+        "otlp_file",
+        "test",
+    ],
+    target_compatible_with = select({
+        ":json_writer_nlohmann_enabled": [],
+        "//conditions:default": ["@platforms//:incompatible"],
+    }),
+    deps = [
+        ":otlp_file_exporter",
+        "//api",
+        "//sdk/src/metrics",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "otlp_file_log_record_exporter_default_json_writer_test",
+    srcs = ["test/otlp_file_log_record_exporter_default_json_writer_test.cc"],
+    tags = [
+        "otlp",
+        "otlp_file",
+        "test",
+    ],
+    target_compatible_with = select({
+        ":json_writer_nlohmann_enabled": [],
+        "//conditions:default": ["@platforms//:incompatible"],
+    }),
+    deps = [
+        ":otlp_file_log_record_exporter",
+        "//api",
+        "//sdk/src/metrics",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "otlp_file_metric_exporter_default_json_writer_test",
+    srcs = ["test/otlp_file_metric_exporter_default_json_writer_test.cc"],
+    tags = [
+        "otlp",
+        "otlp_file",
+        "test",
+    ],
+    target_compatible_with = select({
+        ":json_writer_nlohmann_enabled": [],
+        "//conditions:default": ["@platforms//:incompatible"],
+    }),
+    deps = [
+        ":otlp_file_metric_exporter",
+        "//api",
+        "//sdk/src/metrics",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
 otel_cc_benchmark(
     name = "otlp_grpc_exporter_benchmark",
     srcs = ["test/otlp_grpc_exporter_benchmark.cc"],
@@ -1065,6 +1251,23 @@ otel_cc_benchmark(
     ],
 )
 
+otel_cc_benchmark(
+    name = "otlp_file_client_json_benchmark",
+    srcs = ["benchmark/otlp_file_client_json_benchmark.cc"],
+    tags = [
+        "benchmark",
+        "otlp",
+        "otlp_file",
+        "test",
+    ],
+    deps = [
+        ":otlp_file_client",
+        "//sdk/src/common:global_log_handler",
+        "@com_github_opentelemetry_proto//:common_proto_cc",
+        "@com_github_opentelemetry_proto//:trace_service_proto_cc",
+    ],
+)
+
 otel_cc_benchmark(
     name = "otlp_recordable_benchmark",
     srcs = ["test/otlp_recordable_benchmark.cc"],