feat: [Geneva Exporter] FFI Interface for Geneva Exporter (#419)

Author: lalitb

opentelemetry-exporter-geneva/geneva-uploader-ffi/Cargo.toml

@@ -5,7 +5,23 @@ edition = "2021"
 license = "Apache-2.0"
 rust-version = "1.75.0"
 
+[lib]
+crate-type = ["cdylib", "staticlib", "rlib"]
+
 [dependencies]
+geneva-uploader = { path = "../geneva-uploader" }
+opentelemetry-proto = { workspace = true, default-features = false, features = ["logs", "gen-tonic-messages"] }
+tokio = { version = "1.0", features = ["rt-multi-thread"] }
+prost = "0.13"
+
+[features]
+mock_auth = ["geneva-uploader/mock_auth"]
 
 [lints]
 workspace = true
+
+[dev-dependencies]
+otlp_builder = { path = "examples/otlp_builder" }
+wiremock = "0.6"
+base64 = "0.22"
+chrono = "0.4"

opentelemetry-exporter-geneva/geneva-uploader-ffi/examples/Makefile

@@ -0,0 +1,63 @@
+# Makefile for building and running the C FFI example (local to examples/)
+# This focuses only on compiling c_example.c against the built Rust FFI libs.
+
+.PHONY: all run build-rust build-otlp c-example clean verify-header help
+
+# Defaults: build only (do not run)
+all: build-rust build-otlp $(BINARY)
+
+# Paths relative to this examples/ directory
+RUST_CRATE_DIR := ..
+INCLUDE_DIR    := ../include
+LIB_DIR        := ../../../target/release
+LIB_DIR_DEPS   := $(LIB_DIR)/deps
+BINARY         := c_example_test
+
+# Build the Rust FFI library (release)
+build-rust:
+	@echo "Building Rust FFI library..."
+	@cd $(RUST_CRATE_DIR) && cargo build --release
+
+# Build the example-only otlp_builder (release)
+build-otlp:
+	@echo "Building otlp_builder (cdylib + rlib)..."
+	@cd otlp_builder && cargo build --release
+
+# Build the C example binary
+$(BINARY): c_example.c build-rust build-otlp
+	@echo "Building C example..."
+	@gcc -std=c11 -o $(BINARY) c_example.c \
+		-I$(INCLUDE_DIR) \
+		-L$(LIB_DIR) -L$(LIB_DIR_DEPS) \
+		-lgeneva_uploader_ffi -lotlp_builder \
+		-Wl,-rpath,@loader_path/../../../target/release \
+		-Wl,-rpath,@loader_path/../../../target/release/deps \
+		-lpthread -ldl -lm
+
+# Run the example with proper dynamic library path for macOS/Linux
+run: $(BINARY)
+	@echo "Running C example..."
+	@DYLD_LIBRARY_PATH=$(LIB_DIR):$(LIB_DIR_DEPS) LD_LIBRARY_PATH=$(LIB_DIR):$(LIB_DIR_DEPS) ./$(BINARY)
+
+# Alias
+c-example: run
+
+# Quick header verification (compile-only)
+verify-header:
+	@echo "Verifying C header compatibility..."
+	@gcc -c c_example.c -I$(INCLUDE_DIR) -o /tmp/test_header.o && echo "✓ C header is valid" || echo "✗ C header has issues"
+	@rm -f /tmp/test_header.o
+
+# Clean example build artifacts
+clean:
+	@rm -f $(BINARY)
+
+help:
+	@echo "Targets:"
+	@echo "  all           - Build Rust lib + otlp_builder + C example binary (default)"
+	@echo "  run           - Build and run the C example (requires env vars)"
+	@echo "  c-example     - Same as 'run'"
+	@echo "  build-rust    - Build the Rust FFI library in release mode"
+	@echo "  build-otlp    - Build the otlp_builder cdylib/rlib (release)"
+	@echo "  verify-header - Compile-check the header with the example"
+	@echo "  clean         - Remove the C example binary"

opentelemetry-exporter-geneva/geneva-uploader-ffi/examples/c_example.c

@@ -0,0 +1,164 @@
+/*
+ * Geneva FFI C Example (synchronous only)
+ *
+ * This example demonstrates:
+ * - Reading configuration from environment
+ * - Creating a Geneva client via geneva_client_new (out-param)
+ * - Encoding/compressing ResourceLogs
+ * - Uploading batches synchronously with geneva_upload_batch_sync
+ *
+ * Note: The non-blocking callback-based mechanism has been removed.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <stdint.h>
+#include "../include/geneva_ffi.h"
+
+/* Prototypes from the example-only builder dylib (otlp_builder) */
+extern int geneva_build_otlp_logs_minimal(const char* body_utf8,
+                                          const char* resource_key,
+                                          const char* resource_value,
+                                          uint8_t** out_ptr,
+                                          size_t* out_len);
+extern void geneva_free_buffer(uint8_t* ptr, size_t len);
+
+/* Helper to read env or default */
+static const char* get_env_or_default(const char* name, const char* defval) {
+    const char* v = getenv(name);
+    return v ? v : defval;
+}
+
+
+int main(void) {
+    printf("Geneva FFI Example (synchronous API)\n");
+    printf("====================================\n\n");
+
+    /* Required env */
+    const char* endpoint      = getenv("GENEVA_ENDPOINT");
+    const char* environment   = getenv("GENEVA_ENVIRONMENT");
+    const char* account       = getenv("GENEVA_ACCOUNT");
+    const char* namespaceName = getenv("GENEVA_NAMESPACE");
+    const char* region        = getenv("GENEVA_REGION");
+    const char* cfg_ver_str   = getenv("GENEVA_CONFIG_MAJOR_VERSION");
+
+    if (!endpoint || !environment || !account || !namespaceName || !region || !cfg_ver_str) {
+        printf("Missing required environment variables!\n");
+        printf("  GENEVA_ENDPOINT\n");
+        printf("  GENEVA_ENVIRONMENT\n");
+        printf("  GENEVA_ACCOUNT\n");
+        printf("  GENEVA_NAMESPACE\n");
+        printf("  GENEVA_REGION\n");
+        printf("  GENEVA_CONFIG_MAJOR_VERSION\n");
+        return 1;
+    }
+
+    int cfg_ver = atoi(cfg_ver_str);
+    if (cfg_ver <= 0) {
+        printf("Invalid GENEVA_CONFIG_MAJOR_VERSION: %s\n", cfg_ver_str);
+        return 1;
+    }
+
+    /* Optional env with defaults */
+    const char* tenant       = get_env_or_default("GENEVA_TENANT", "default-tenant");
+    const char* role_name    = get_env_or_default("GENEVA_ROLE_NAME", "default-role");
+    const char* role_instance= get_env_or_default("GENEVA_ROLE_INSTANCE", "default-instance");
+
+    /* Certificate auth if both provided; otherwise managed identity */
+    const char* cert_path     = getenv("GENEVA_CERT_PATH");
+    const char* cert_password = getenv("GENEVA_CERT_PASSWORD");
+    int32_t auth_method = (cert_path && cert_password) ? GENEVA_AUTH_CERTIFICATE : GENEVA_AUTH_MANAGED_IDENTITY;
+
+    printf("Configuration:\n");
+    printf("  Endpoint: %s\n", endpoint);
+    printf("  Environment: %s\n", environment);
+    printf("  Account: %s\n", account);
+    printf("  Namespace: %s\n", namespaceName);
+    printf("  Region: %s\n", region);
+    printf("  Config Major Version: %d\n", cfg_ver);
+    printf("  Tenant: %s\n", tenant);
+    printf("  Role Name: %s\n", role_name);
+    printf("  Role Instance: %s\n", role_instance);
+    printf("  Auth Method: %s\n", auth_method == GENEVA_AUTH_CERTIFICATE ? "Certificate" : "Managed Identity");
+    if (auth_method == GENEVA_AUTH_CERTIFICATE) {
+        printf("  Cert Path: %s\n", cert_path);
+    }
+    printf("\n");
+
+    /* Build config */
+    GenevaConfig cfg = {
+        .endpoint = endpoint,
+        .environment = environment,
+        .account = account,
+        .namespace_name = namespaceName,
+        .region = region,
+        .config_major_version = (uint32_t)cfg_ver,
+        .auth_method = auth_method,
+        .tenant = tenant,
+        .role_name = role_name,
+        .role_instance = role_instance,
+    };
+    if (auth_method == GENEVA_AUTH_CERTIFICATE) {
+        cfg.auth.cert.cert_path = cert_path;
+        cfg.auth.cert.cert_password = cert_password;
+    } else {
+        cfg.auth.msi.objid = NULL;
+    }
+
+    /* Create client */
+    GenevaClientHandle* client = NULL;
+    GenevaError rc = geneva_client_new(&cfg, &client);
+    if (rc != GENEVA_SUCCESS || client == NULL) {
+        printf("Failed to create Geneva client (code=%d)\n", rc);
+        return 1;
+    }
+    printf("Geneva client created.\n");
+
+    /* Create ExportLogsServiceRequest bytes via FFI builder */
+    size_t data_len = 0;
+    uint8_t* data = NULL;
+    GenevaError brc = geneva_build_otlp_logs_minimal("hello from c ffi", "service.name", "c-ffi-example", &data, &data_len);
+    if (brc != GENEVA_SUCCESS || data == NULL || data_len == 0) {
+        printf("Failed to build OTLP payload (code=%d)\n", brc);
+        geneva_client_free(client);
+        return 1;
+    }
+
+    /* Encode and compress to batches */
+    EncodedBatchesHandle* batches = NULL;
+    GenevaError enc_rc = geneva_encode_and_compress_logs(client, data, data_len, &batches);
+    if (enc_rc != GENEVA_SUCCESS || batches == NULL) {
+        printf("Encode/compress failed (code=%d)\n", enc_rc);
+        geneva_free_buffer(data, data_len);
+        geneva_client_free(client);
+        return 1;
+    }
+
+    size_t n = geneva_batches_len(batches);
+    printf("Encoded %zu batch(es)\n", n);
+
+    /* Upload synchronously, batch by batch */
+    GenevaError first_err = GENEVA_SUCCESS;
+    for (size_t i = 0; i < n; i++) {
+        GenevaError r = geneva_upload_batch_sync(client, batches, i);
+        if (r != GENEVA_SUCCESS) {
+            first_err = r;
+            printf("Batch %zu upload failed with error %d\n", i, r);
+            break;
+        }
+    }
+
+    /* Cleanup */
+    geneva_batches_free(batches);
+    geneva_free_buffer(data, data_len);
+    geneva_client_free(client);
+
+    if (first_err == GENEVA_SUCCESS) {
+        printf("All batches uploaded successfully.\n");
+        return 0;
+    }
+    printf("Upload finished with error code: %d\n", first_err);
+    return 1;
+}

opentelemetry-exporter-geneva/geneva-uploader-ffi/examples/otlp_builder/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "otlp_builder"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.75.0"
+license = "Apache-2.0"
+
+[lib]
+crate-type = ["rlib", "cdylib"]
+
+[lints]
+workspace = true
+
+[dependencies]
+# Use the repo's opentelemetry-proto crate directly
+opentelemetry-proto = { version = "0.30", default-features = false, features = ["logs", "gen-tonic-messages"] }
+prost = "0.13"

opentelemetry-exporter-geneva/geneva-uploader-ffi/examples/otlp_builder/src/builder.rs

@@ -0,0 +1,70 @@
+use opentelemetry_proto::tonic::collector::logs::v1::ExportLogsServiceRequest;
+use opentelemetry_proto::tonic::common::v1::any_value::Value as AnyValueValue;
+use opentelemetry_proto::tonic::common::v1::{AnyValue, KeyValue};
+use opentelemetry_proto::tonic::logs::v1::{LogRecord, ResourceLogs, ScopeLogs};
+use opentelemetry_proto::tonic::resource::v1::Resource;
+use prost::Message;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Pure Rust helper to build a minimal OTLP ExportLogsServiceRequest as bytes.
+/// This is shared by the C example dylib and test-only usage via include! from lib.rs tests.
+///
+/// **Note**: This function is only intended for examples and unit tests, not for external use.
+pub fn build_otlp_logs_minimal(
+    event_name: &str,
+    body: &str,
+    resource_kv: Option<(&str, &str)>,
+) -> Vec<u8> {
+    let mut resource_attrs: Vec<KeyValue> = Vec::new();
+    if let Some((k, v)) = resource_kv {
+        resource_attrs.push(KeyValue {
+            key: k.to_string(),
+            value: Some(AnyValue {
+                value: Some(AnyValueValue::StringValue(v.to_string())),
+            }),
+        });
+    }
+
+    let now_nanos: u64 = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_nanos() as u64;
+
+    let log_record = LogRecord {
+        time_unix_nano: now_nanos,
+        observed_time_unix_nano: 0,
+        severity_number: 0,
+        severity_text: String::new(),
+        event_name: event_name.to_string(),
+        body: Some(AnyValue {
+            value: Some(AnyValueValue::StringValue(body.to_string())),
+        }),
+        attributes: Vec::new(),
+        dropped_attributes_count: 0,
+        flags: 0,
+        trace_id: Vec::new(),
+        span_id: Vec::new(),
+    };
+
+    let scope_logs = ScopeLogs {
+        scope: None,
+        log_records: vec![log_record],
+        schema_url: String::new(),
+    };
+
+    let resource_logs = ResourceLogs {
+        resource: Some(Resource {
+            attributes: resource_attrs,
+            dropped_attributes_count: 0,
+            entity_refs: Vec::new(),
+        }),
+        scope_logs: vec![scope_logs],
+        schema_url: String::new(),
+    };
+
+    let req = ExportLogsServiceRequest {
+        resource_logs: vec![resource_logs],
+    };
+
+    req.encode_to_vec()
+}