大家好，今天要和大家介紹我近期開發的一個開源專案 replication_checker_rs 如果你想用一個輕量、可讀性高的工具實時觀察 PostgreSQL 邏輯複寫（logical replication）流，或想把複寫協議的學習變成可執行的實驗場，replication_checker_rs 是一個不錯的起點：它是 Rust 實現 PostgreSQL logical replication protocol 使用 libpq-sys 的實作，能連上資料庫、建立 replication slot，並將 INSERT / UPDATE / DELETE / TRUNCATE 等變更以可讀格式顯示出來。(https://github.com/isdaniel/replication_checker_rs)

為什麼會想用它？

• 學習角度：它直接實作 PostgreSQL 的 logical replication protocol（WAL message parsing、relation/tuple 格式）以可讀、可改造的 Rust 程式碼呈現，適合希望理解底層協議的人。
• 快速驗證：想知道 publication 有沒有正確產生事件、或某些 schema 變更會如何呈現時，可以直接跑這個工具觀察實際輸出。
• Rust + libpq 真實範例：展示如何用 libpq-sys 與 Tokio 做低階連線管理與 parser 實作
• 延伸空間大：可以把它當作 PoC（proof of concept），加上 JSON 化、推到 Kafka/Redis、做到可重啟的 consumer。

功能與限制（快速掃描）

主要功能

• 用作邏輯複寫客戶端（logical replication client），可建立 replication slot 並接收變更。
• 支援顯示 BEGIN、COMMIT、INSERT、UPDATE、DELETE、TRUNCATE 以及 relation／tuple 資訊，並能處理 streaming（大型）交易。

目前限制

• 目前只把變更顯示為人類可讀格式，沒有把事件推到 Kafka/Redis 等下游處理器。
• 只對文字型別（text types）有良好處理；binary 類型會以 raw 形式顯示。
• slot 管理、錯誤復原邏輯較簡單（遇到大部分錯誤會結束程式）

實作前準備（PostgreSQL 與系統）

1. PostgreSQL 必須開啟 logical WAL：wal_level = logical（修改後需重啟 PostgreSQL）。這是 logical replication 的必要條件。
2. 建立 publication（只複寫你想要的 table，或 FOR ALL TABLES）：CREATE PUBLICATION my_publication FOR TABLE table1, table2;。
3. 建立有 replication 權限的 user：例如 CREATE USER replicator WITH REPLICATION LOGIN PASSWORD 'password'; 並給予必要的 SELECT 權限。
4. 系統相依套件：需要 libpq 開發檔（例如 Debian/Ubuntu 的 libpq-dev、macOS 用 Homebrew 安裝 postgresql），並使用 Rust 1.70+。

請注意：PostgreSQL DB 版本必須等於或高於版本 14，更多資訊請參閱以下連結。

https://www.postgresql.org/docs/14/protocol-replication.html
https://www.postgresql.org/docs/current/protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS

PostgreSQL 設定（必要）

1. postgresql.conf：

1
2
3

wal_level = logical
max_replication_slots = 10    # 視需求調整
max_wal_senders = 10

修改後重啟 PostgreSQL。

2. 建 publication 與 replication user（在 psql 下執行）：

1
2
3
4

-- 建 replication user
CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD 'replicator_pw';
-- 建 publication（只複寫特定 table 或使用 FOR ALL TABLES）
CREATE PUBLICATION my_publication FOR TABLE public.my_table;

注意：不要無限制地建立 replication slot（未刪除會造成 WAL 快速累積），測試時留意 WAL 使用量。

快速上手（編譯 & 執行）

從原始碼編譯

1
2
3

git clone https://github.com/isdaniel/replication_checker_rs.git
cd replication_checker_rs
cargo build --release

（注意系統需先安裝 libpq 開發庫）。

範例執行方式（README 範例改寫，實務上把 db 參數用空格分開的 key-value 傳入）

1
2
3
4
5
6

# 設定 slot / publication 名稱（可用環境變數）
export slot_name="my_slot"
export pub_name="my_publication"

# 執行（參數順序為 key value key value ...）
./target/release/pg_replica_rs user azureuser **replication database** host 127.0.0.1 dbname redis_fdw_rs port 5432

連接字串需要使用 replication database 代表是 replication 操作
你也可以用 RUST_LOG 控制日誌等級（例：RUST_LOG=debug）。

Docker 方式

1
2
3

docker build -t pg_replica_rs .
docker run -e slot_name=my_slot -e pub_name=my_pub \
  pg_replica_rs user postgres password secret host host.docker.internal port 5432 dbname mydb

方便在隔離環境做測試。

實戰：建立 publication、產生測試資料、觀察輸出

在資料庫上建立測試 table 與 publication

1
2
3
4
5
6

CREATE TABLE public.my_table (
  id serial primary key,
  msg text
);

CREATE PUBLICATION my_publication FOR TABLE public.my_table;

在另一個 psql session 產生變更

1
2
3

INSERT INTO public.my_table (msg) VALUES ('hello replication');
UPDATE public.my_table SET msg = 'altered' WHERE id = 1;
DELETE FROM public.my_table WHERE id = 1;

觀察 replication_checker_rs 的輸出（示例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

025-08-10T02:57:54.417412Z  INFO Started receiving data from database server
2025-08-10T02:58:01.488499Z  INFO BEGIN: Xid 1522
2025-08-10T02:58:01.489158Z  INFO Received relation info for public.t1
2025-08-10T02:58:01.489235Z  INFO TRUNCATE
2025-08-10T02:58:01.489255Z  INFO public.t1
2025-08-10T02:58:01.489318Z  INFO COMMIT: flags: 0, lsn: 43614824, end_lsn: 43614944, commit_time: 2025-08-10 02:58:01.484 UTC
2025-08-10T02:58:07.583760Z  INFO BEGIN: Xid 1523
2025-08-10T02:58:07.583925Z  INFO Received relation info for public.t1
2025-08-10T02:58:07.584000Z  INFO table public.t1: INSERT:
2025-08-10T02:58:07.584012Z  INFO a: 1
2025-08-10T02:58:07.584040Z  INFO table public.t1: INSERT:
2025-08-10T02:58:07.584062Z  INFO a: 2
2025-08-10T02:58:07.584104Z  INFO COMMIT: flags: 0, lsn: 43615128, end_lsn: 43615176, commit_time: 2025-08-10 02:58:07.580 UTC

程式碼結構與關鍵模組導覽

（以 repo 常見的檔案分佈為範例）

• main.rs：啟動、參數解析、log 設定
• server.rs / connection.rs：與 Postgres 建立 replication 連線、處理 libpq loop
• parser.rs：負責把 raw WAL message 解析成內部事件（BEGIN/RELATION/INSERT/UPDATE/DELETE/TRUNCATE/COMMIT）
• types.rs：定義 relation、tuple 與欄位型別
• utils.rs：byte 解析、LSN 處理、輔助 function

深入：實踐中的概念與操作建議

下面幾點是把工具從「觀察器」進化到「可實際應用」時會用到的概念與工程建議。

1. Replication Slot

   • Slot 決定了你從哪個 WAL LSN 開始讀，並讓 PostgreSQL 保留 WAL（直到被確認消費）。測試時注意不要無限建立未刪除的 slot（會造成 WAL 累積）。replication_checker_rs 可建立 slot，但目前在程式中 slot cleanup 還是簡單處理，所以測試環境中你要管理好。

2. Publication 與 Schema 一致性

   • Publication 決定哪些 table 的變更會被發送。上線前請確認 schema（尤其 REPLICA IDENTITY、nullable、type 改動）在 source 與 downstream 處理端的一致性，否則解析或重放會有問題。replication_checker_rs 會顯示 relation 資訊，能幫你驗證。

3. Streaming 交易

   • 對大交易（very large transactions），Postgres 可能以 streaming 模式傳送。此專案已處理 streaming 交易，這讓它在面對大批量資料變更時不會輕易崩潰。(

4. Feedback（ack）機制

   • Logical replication protocol 支援回報已處理的 WAL 位置（可用於讓 primary safe remove WAL）。專案實作有 feedback 機制，但在 production 要確保回報策略（多久 ack、持久化 LSN 等）與你下游同步策略一致。

5. 從「顯示」到「處理」：把事件送到下游

   • 如果你要把變更送到 Kafka、Redis 或寫入另一個 DB，建議把 parser 與 message handling 拆成兩層：（1）可靠地接收並 ack WAL（LSN）、（2）異步或批次地把事件轉送到下游並重試。目前 replication_checker_rs 主要做第（1）與可視化，延伸第（2）需要你加上連線池、backpressure 與錯誤重試。

實務上常見問題（與排解）

• libpq not found：請安裝系統的 PostgreSQL 開發套件（如 libpq-dev、postgresql-devel 或 Homebrew 的 postgresql）。
• 權限錯誤：Replication user 需要 REPLICATION 權限，且 publication 應包含你想觀察的 tables。
• Slot 已存在：若 slot 名稱衝突，請手動刪除舊 slot 或指定不同名稱再試。

延伸建議（如果你想把它用到更真實的場景）

1. 將輸出轉成 structured JSON 並發到 Kafka 或 Event Hub（便於 downstream consumer 處理）。
2. 增加 slot cleanup & resume 機制：遇錯不要直接停，保存最後 ack 的 LSN，重啟時從該位置恢復。
3. 支援 binary 類型與更完整的 type mapping（目前以 raw 顯示 binary）。
4. 把 replication_checker_rs 包成一個可監控的 service，加上 metrics（Prometheus）與 health-check endpoint。
   這些方向都屬於從 PoC → production 的典型演進路線。

結語

replication_checker_rs 是一個很實用的學習與測試工具：它把 PostgreSQL logical replication protocol 的各個重要面向（slot、publication、BEGIN/COMMIT、tuple parsing、streaming 交易、feedback）用 Rust + libpq 呈現出來，適合用來做教學、驗證複寫行為或作為你自製複寫處理器的起點。想進一步把它變成 production-ready，需要在錯誤復原、slot 管理、下游整合跟 binary type 處理上補強。(GitHub)

• replication_checker_rs
• 歡迎 Star、開 issue、PR 一起改進專案！

此文作者：Daniel Shih(石頭)
此文地址： https://isdaniel.github.io/logical-replication-checker-replication_checker_rs/
版權聲明：本博客所有文章除特別聲明外，均採用 CC BY-NC-SA 3.0 TW 許可協議。轉載請註明出處！

🚀 Building a Simple PostgreSQL FDW with Rust and pgrx

PostgreSQL Foreign Data Wrappers (FDW) enable PostgreSQL to query external data sources as if they were regular tables. Traditionally, FDWs are written in C, but with pgrx, we can now build PostgreSQL extensions — including FDWs — in Rust, unlocking safety and modern tooling.

In this post, we’ll walk through creating a simple FDW using Rust and pgrx that simulates reading rows from an external source (e.g., Redis or API). While it’s a stub, it demonstrates how to implement the core FDW lifecycle.

🛠️ What Can You Build with pgrx?

• ✅ SQL Functions: Scalar, aggregate, and set-returning functions.
• ✅ Custom Types: Define composite types or enums in Rust.
• ✅ Foreign Data Wrappers (FDWs): Like the one in your example — connect PostgreSQL to external systems (Redis, APIs, file systems, etc.).
• ✅ Index Access Methods: Implement new index types.
• ✅ Background Workers: Run tasks in the background inside PostgreSQL.
• ✅ Hooks: Intercept or modify PostgreSQL internal behavior (like planner or executor hooks).

🌐 Under the hood:

• PostgreSQL communicates via C APIs.
• pgrx provides Rust-safe bindings to these APIs.
• Memory management is handled carefully via PgMemoryContexts, matching PostgreSQL’s memory context model.
• Rust functions are exposed to PostgreSQL as SQL-callable functions with the #[pg_extern] macro.

🏗️ Key Components of an default_fdw

PostgreSQL FDWs consist of several callback functions that handle different phases of query planning and execution:

Example extension default_fdw

• Planning Phase:

  • GetForeignRelSize: Estimate rows.
  • GetForeignPaths: Generate access paths.
  • GetForeignPlan: Create the scan plan.

• Execution Phase:

  • BeginForeignScan: Initialize the scan.
  • IterateForeignScan: Produce each row.
  • ReScanForeignScan: Restart the scan if needed.
  • EndForeignScan: Cleanup.

How to use

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

create foreign data wrapper default_wrapper
  handler default_fdw_handler;

create server my_default_server
  foreign data wrapper default_wrapper
  options (
    foo 'bar'
  );

create foreign table hello (
  id bigint,
  col text
)
server my_default_server options (
foo 'bar'
);

Then we can select hello table.

1

select * from hello;

🔧 Setting Up the FDW Handler

The entry point is the FDW handler function, which PostgreSQL calls to retrieve a set of function pointers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

#[pg_extern(create_or_replace)]
pub extern "C" fn default_fdw_handler() -> PgBox<pg_sys::FdwRoutine> {
    log!("> default_fdw_handler");
    unsafe {
        let mut fdw_routine = PgBox::<pg_sys::FdwRoutine, AllocatedByRust>::alloc_node(pg_sys::NodeTag::T_FdwRoutine);

        // Planning callbacks
        fdw_routine.GetForeignRelSize = Some(get_foreign_rel_size);
        fdw_routine.GetForeignPaths = Some(get_foreign_paths);
        fdw_routine.GetForeignPlan = Some(get_foreign_plan);
        fdw_routine.ExplainForeignScan = Some(explain_foreign_scan);

        // Execution callbacks
        fdw_routine.BeginForeignScan = Some(begin_foreign_scan);
        fdw_routine.IterateForeignScan = Some(iterate_foreign_scan);
        fdw_routine.ReScanForeignScan = Some(re_scan_foreign_scan);
        fdw_routine.EndForeignScan = Some(end_foreign_scan);

        fdw_routine.into_pg_boxed()
    }
}

📦 Extracting Foreign Table Options

PostgreSQL allows specifying options like hostnames or credentials when creating a foreign table. This function retrieves those options:

1
2
3

unsafe fn get_foreign_table_options(relid: pg_sys::Oid) -> HashMap<String, String> {
    ...
}

This is crucial when your FDW needs to connect to external systems like Redis, REST APIs, or filesystems.

📊 Planner Callbacks

1️⃣ GetForeignRelSize

Estimates the number of rows in the foreign table.

1
2
3
4
5
6
7

#[pg_guard]
extern "C" fn get_foreign_rel_size(..., baserel: *mut pg_sys::RelOptInfo, ...) {
    log!("> get_foreign_rel_size");
    unsafe {
        (*baserel).rows = 1000.0;
    }
}

2️⃣ GetForeignPaths

Defines possible access paths for the planner.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#[pg_guard]
extern "C" fn get_foreign_paths(..., baserel: *mut pg_sys::RelOptInfo, ...) {
    log!("> get_foreign_paths");
    unsafe {
        let path = pg_sys::create_foreignscan_path(
            ...,
            (*baserel).rows,
            10.0,   // startup cost
            100.0,  // total cost
            ...
        );
        pg_sys::add_path(baserel, path as *mut pg_sys::Path);
    }
}

3️⃣ GetForeignPlan

Generates the actual execution plan.

1
2
3
4
5
6
7

#[pg_guard]
extern "C" fn get_foreign_plan(...) -> *mut pg_sys::ForeignScan {
    log!("> get_foreign_plan");
    unsafe {
        pg_sys::make_foreignscan(...)
    }
}

▶️ Execution Callbacks

🏁 BeginForeignScan

Initializes the scan.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#[pg_guard]
extern "C" fn begin_foreign_scan(node: *mut pg_sys::ForeignScanState, ...) {
    log!("> begin_foreign_scan");
    unsafe {
        let relid = (*(*node).ss.ss_currentRelation).rd_id;
        let options = get_foreign_table_options(relid);
        log!("Foreign table options: {:?}", options);

        let state = PgMemoryContexts::CurrentMemoryContext
            .leak_and_drop_on_delete(RedisFdwState { row: 0 });

        (*node).fdw_state = state as *mut std::ffi::c_void;
    }
}

🔁 IterateForeignScan

Produces rows one at a time.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

#[pg_guard]
extern "C" fn iterate_foreign_scan(node: *mut pg_sys::ForeignScanState) -> *mut pg_sys::TupleTableSlot {
    log!("> iterate_foreign_scan");

    unsafe {
        let state = &mut *((*node).fdw_state as *mut RedisFdwState);
        let slot = (*node).ss.ss_ScanTupleSlot;
        let tupdesc = (*slot).tts_tupleDescriptor;
        let natts = (*tupdesc).natts as usize;

        if state.row >= 5 {
            exec_clear_tuple(slot);
            return slot;
        }

        exec_clear_tuple(slot);

        let values_ptr = PgMemoryContexts::For((*slot).tts_mcxt)
            .palloc(std::mem::size_of::<pg_sys::Datum>() * natts) as *mut pg_sys::Datum;

        let nulls_ptr = PgMemoryContexts::For((*slot).tts_mcxt)
            .palloc(std::mem::size_of::<bool>() * natts) as *mut bool;

        *values_ptr.add(0) = (state.row + 1).into();
        let name = format!("hello_{}", state.row + 1);
        let cstring = CString::new(name).unwrap();
        *values_ptr.add(1) = Datum::from(pg_sys::cstring_to_text(cstring.as_ptr()));

        *nulls_ptr.add(0) = false;
        *nulls_ptr.add(1) = false;

        (*slot).tts_values = values_ptr;
        (*slot).tts_isnull = nulls_ptr;

        pg_sys::ExecStoreVirtualTuple(slot);

        state.row += 1;

        slot
    }
}

This example emits five rows with (id, name) pairs like (1, hello_1).

🔄 ReScanForeignScan

Handles rescan requests.

1
2
3
4

#[pg_guard]
extern "C" fn re_scan_foreign_scan(_node: *mut pg_sys::ForeignScanState) {
    log!("> re_scan_foreign_scan");
}

🛑 EndForeignScan

Frees resources.

1
2
3
4
5
6
7
8
9

#[pg_guard]
extern "C" fn end_foreign_scan(node: *mut pg_sys::ForeignScanState) {
    log!("> end_foreign_scan");
    unsafe {
        if !(*node).fdw_state.is_null() {
            (*node).fdw_state = std::ptr::null_mut();
        }
    }
}

🗒️ Utilities

Tuple clearing is handled by this helper:

1
2
3
4
5

unsafe fn exec_clear_tuple(slot: *mut pg_sys::TupleTableSlot) {
    if let Some(clear) = (*(*slot).tts_ops).clear {
        clear(slot);
    }
}

🏁 Conclusion

This post walked you through the basics of building a PostgreSQL FDW using Rust and pgrx. While this example generates dummy data, the same structure can be extended to connect with real-world systems like Redis, REST APIs, or message queues.

🚀 Next Steps

• Add connection logic to Redis or any backend.
• Support INSERT, UPDATE, DELETE by implementing the modification callbacks.
• Package and distribute as a PostgreSQL extension.

📚 References

• pgrx GitHub
• PostgreSQL FDW API Documentation

If you’d like, I can help refine this post further, format it for Medium/Dev.to, or extend it with Redis connection examples. Would you like that?

此文作者：Daniel Shih(石頭)
此文地址： https://isdaniel.github.io/rust-pgrx-extension-fdw/
版權聲明：本博客所有文章除特別聲明外，均採用 CC BY-NC-SA 3.0 TW 許可協議。轉載請註明出處！

If you’ve ever struggled to instrument legacy apps or non-standard services for observability, OpenTelemetry_SideCar is here to help. This project offers a non-intrusive way to export metrics and traces via OpenTelemetry using a sidecar approach — no SDK required in your main app.

🌐 Project Overview

📦 Repo: isdaniel/OpenTelemetry_SideCar

OpenTelemetry_SideCar is a standalone proxy service that collects metrics and traces outside of your application and forwards them to a telemetry backend (e.g., Prometheus, Jaeger, or Azure Monitor).

💡 Why a Sidecar?

In cloud-native systems, a sidecar is a helper container or process that runs alongside your main application. It can observe, extend, or enhance app behavior without changing application code. This pattern is ideal for adding observability when:

• You can’t modify the original code (e.g., closed-source, legacy binaries).
• You want to centralize telemetry logic.
• You’re aiming for a unified instrumentation strategy.

🧠 Key Concepts

📊 OpenTelemetry

OpenTelemetry is the CNCF-backed observability framework offering a vendor-neutral standard to collect metrics, logs, and traces.

This project leverages:

• OTLP (OpenTelemetry Protocol) for data transport
• Push-based metrics collection via HTTP endpoints
• Custom trace generation from event messages

🧱 Sidecar Design Pattern

This service runs in parallel with your main app and exposes lightweight endpoints for:

• Sending metrics via /metrics
• Sending traces via /trace

Apps interact with the sidecar using simple HTTP POST requests.

⚙️ How It Works

Architecture

The project consists of the following components:

• .NET Web Application: A simple web service with custom metrics and tracing- OpenTelemetry Collector: Receives telemetry data and exports it to backends
• Prometheus: Time-series database for storing and querying metrics- Jaeger: Distributed tracing system for monitoring and troubleshooting
• Grafana: Visualization and dashboarding platform

1
2
3
4
5
6
7
8
9
10
11
12
13

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Rust We        │     │                 │     │                 │
│  .NET App       │────▶│  OTel Collector │────▶│  Prometheus     │
│                 │     │                 │     │                 │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │                        ▲
                                 │                        │
                                 ▼                        │
                        ┌─────────────────┐      ┌────────┴────────┐
                        │                 │      │                 │
                        │  Jaeger         │      │  Grafana        │
                        │                 │      │                 │
                        └─────────────────┘      └─────────────────┘

Features

• Custom metrics using OpenTelemetry Metrics API- Distributed tracing with OpenTelemetry Tracing API
• Nested HTTP calls with context propagation- Prometheus metrics collection
• Jaeger trace visualization- Grafana dashboards for metrics visualization

Prerequisites

• Docker and Docker Compose
• .NET 9.0 SDK (for local development)

Getting Started

Running the Application

Clone the repository:

1
2

git clone https://github.com/yourusername/OpenTelemetry_SideCar.git
cd OpenTelemetry_SideCar

Start the services using Docker Compose:

1

docker-compose up -d

1. Access the application: Web Application: http://localhost:8080 - Nested Greeting: http://localhost:8080/NestedGreeting?nestlevel=3

Accessing Observability Tools

• Prometheus: http://localhost:9090
  • Query metrics with PromQL - Example: greetings_count_total
• Jaeger UI: http://localhost:16686
  • View distributed traces - Filter by service: telemetry_example
• Grafana: http://localhost:3000
  • Default credentials: admin/admin - Pre-configured dashboards for application metrics

Application Endpoints

• / - Returns a simple greeting and increments the greeting counter
• /NestedGreeting?nestlevel=N - Creates a chain of N nested HTTP calls, demonstrating trace context propagation

Configuration Files

• docker-compose.yml: Defines all services and their connections- otel-collector-config.yaml: Configures the OpenTelemetry Collector
• prometheus.yml: Prometheus scraping configuration- Dockerfile: Builds the .NET application

Troubleshooting

Common Issues

1. No metrics in Prometheus:
   • Verify the OpenTelemetry Collector is running: docker-compose ps - Check collector logs: docker-compose logs otel-collector
   • Ensure Prometheus is scraping the collector: http://localhost:9090/targets
2. No traces in Jaeger: - Verify Jaeger is running: docker-compose ps jaeger
   • Check that OTLP is enabled in Jaeger - Generate some traces by accessing the application endpoints
3. Application errors:
   • Check application logs: docker-compose logs app

Development

Local Development

To run the application locally:

1. Navigate to the src directory2. Run dotnet run
   Note: When running locally, you’ll need to update the OTLP endpoint in Program.cs to point to your local OpenTelemetry Collector.

Adding Custom Metrics

1. Create a new meter:

   1	var myMeter = new Meter("MyApp.Metrics", "1.0.0");

2. Create metrics instruments:

   1	var myCounter = myMeter.CreateCounter<int>("my.counter", "Count of operations");

3. Record measurements:

   1	myCounter.Add(1);

4. Register the meter in the OpenTelemetry configuration:

   1	metricsProviderBuilder.AddMeter("MyApp.Metrics");

📥 Example: Sending Metrics

Suppose your app wants to record a counter metric for user logins. All it needs to do is POST to the sidecar:

1
2
3
4
5
6
7
8
9
10
11

curl -X POST http://localhost:8080/metrics \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user_login_total",
    "kind": "counter",
    "value": 1,
    "attributes": {
      "service": "auth-service",
      "status": "success"
    }
  }'

📌 This will be transformed into an OpenTelemetry metric and pushed to your configured OTLP collector.

📡 Example: Sending Traces

To record a trace span (e.g., for a request to /api/data), POST to /trace:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl -X POST http://localhost:8080/trace \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "abc123",
    "span_id": "def456",
    "name": "GET /api/data",
    "kind": "server",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T00:00:01Z",
    "attributes": {
      "http.method": "GET",
      "http.status_code": 200
    }
  }'

The sidecar will:

• Create the span
• Set its metadata and timing
• Export it via OTLP to your backend (e.g., Jaeger or Zipkin)

🛠️ Configuration

Set the following environment variables:

1
2
3

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
OTEL_SERVICE_NAME=my-sidecar
OTEL_METRICS_EXPORT_INTERVAL=1000

These control how frequently data is flushed and where it’s sent.

🔒 No SDK, No Problem

One of the biggest benefits of OpenTelemetry_SideCar is that your main app doesn’t need to:

• Link or compile with any OpenTelemetry SDK
• Maintain exporter or collector logic
• Handle telemetry lifecycle

Your app stays clean — just send HTTP!

🚀 Get Started

1
2
3

git clone https://github.com/isdaniel/OpenTelemetry_SideCar.git
cd OpenTelemetry_SideCar
cargo run

Then, start POSTing traces and metrics from your apps.

🙌 Final Thoughts

OpenTelemetry_SideCar empowers teams to add observability with zero code changes to their applications. It’s perfect for teams looking to modernize telemetry practices without touching production binaries.

If you’re working with mixed environments or maintaining legacy services, give it a try!

⭐️ Star the repo: isdaniel/OpenTelemetry_SideCar

<! Above information summaries from AI. />

此文作者：Daniel Shih(石頭)
此文地址： https://isdaniel.github.io/opentelemetry-sidecar/
版權聲明：本博客所有文章除特別聲明外，均採用 CC BY-NC-SA 3.0 TW 許可協議。轉載請註明出處！