From 534386373272e53301362c0df286c932ce2d25c6 Mon Sep 17 00:00:00 2001
From: Juan Matthys Uys <opyate@gmail.com>
Date: Wed, 30 Mar 2016 13:13:54 +0100
Subject: [PATCH] documentaton for correlation-id plugin

---
 .../images/icons/plugins/correlation-id.png   | Bin 0 -> 985 bytes
 app/_data/plugins.yml                         |   4 ++
 app/plugins/correlation-id.md                 |  48 ++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 app/_assets/images/icons/plugins/correlation-id.png
 create mode 100644 app/plugins/correlation-id.md

diff --git a/app/_assets/images/icons/plugins/correlation-id.png b/app/_assets/images/icons/plugins/correlation-id.png
new file mode 100644
index 0000000000000000000000000000000000000000..5606beff9f4ec979c37e692be7140f2067566706
GIT binary patch
literal 985
zcmV;~119{5P)<h;3K|Lk000e1NJLTq004LZ004Lh1^@s6Ib=4{00006VoOIv0RI30
z001*5eDeSR010qNS#tmY3ljhU3ljkVnw%H_000McNliru-~%2E2|Gk3Kvw_&17=A?
zK~#9!?VP_(R6!U=&t4XE`IA^-fs5U3H1SUiQkW20rL!>l0H~cW;WH?_0F@n$l`*l=
zpb>+`mUyL*%ETq>f`A1W*BcU8cY(b#=ajQRxO4K&Z@xR3E!Ao@_89;k0r!E+z%WuI
z>c9%H06b6AbQ7SoFL(@C1g<(yLGTfnNz-(#RIAknfVavGj%DCx0z6c1kX!*~%fN&D
zC)H||N~Piy6^KToL6&9t;RgwDUAe`lQmIg_R`bKxlKtKDKR+nNm7L>D;<SW~f)y-9
zrX144e67Q?l^vGWciGqqOVm(5+!!tK_;SL9;RpqP`2n-9wyAH0S&184@Oo{R_v_ot
zPxmoC64??x_jxB+xvkW<_MSDm3|?B_jV4#$eLMQI2D3!xGk0+&to`H6;@_%m{Bjp9
z3RbWvSQIP@76r?HQjYb(Tl>m``sV!S?b7bwJFdRn3U-MW1&bNnYaEt&-Oj|*dN*zb
zyF`nE#SHHCKDg69w$r}YK3Ehi3O0l7gTv~JtzegEQLu!O!6DuKiRC=_$bv(^`xE^V
z9n0OHXa&b~_b18>?)AGr?PjLu!D5>v3YH@E!6D&!u((8vf+f@pKIwP8$Nl@B2a8Lz
zC|HV;!6*H$x7YUw-VYW9i-P5}`ruA8s_1(J&x1w5qG0KjKDgT%)ozBjyGJ;8wzL25
z`_G-W`fw{)6f6ohgS(Z9ML!SDXJ}FSVk_7sS`;ky!Kal$R<I~o6fCj#!G~q=NuLK>
z!J=SMu*BL2ce^jX_j2c-?-2<((<|i&EBMA}DVnOBIA4lS@a(08;r{UD4)^apYjlDy
zj==nMA5&u`1_S(Jior5Wjg^?6?&IP}5B9;weI9)4#db#-pZ|Z}-0gE0EeaL|OOSnV
zD0hFXU{SCrSb8mkW4Zfd1&e}3!BVt7_^=GMFSde3!J=RVi-JYLqF_<5C|DG%U<rmJ
zzl$E~$GblvSFm?~0vGJvpTGrs_b2cS1{fcKr<3l>+(nCmMZwY~!JDlEjYh*+DJTcH
zt0%yR){!jBXf~V9R>5dCn`Bv*A6_W~3&3RS=<4dKGZqF52`~pNI~T$637AWOCU6J%
z=$r(@GH^Rh)8?OD^crvzcmgZ|8_rST*w}aX1ei$EbPeD)tm!A<txF%u00000NkvXX
Hu0mjf>Xyt)

literal 0
HcmV?d00001

diff --git a/app/_data/plugins.yml b/app/_data/plugins.yml
index 6232041c5753..20c5f0d65ffa 100644
--- a/app/_data/plugins.yml
+++ b/app/_data/plugins.yml
@@ -91,3 +91,7 @@
     - name: Loggly
       id: loggly
       info: Send request and response logs to Loggly
+
+    - name: Correlation ID
+      id: correlation-id
+      info: Correlate requests and responses using a unique ID
diff --git a/app/plugins/correlation-id.md b/app/plugins/correlation-id.md
new file mode 100644
index 000000000000..91282c5935df
--- /dev/null
+++ b/app/plugins/correlation-id.md
@@ -0,0 +1,48 @@
+---
+id: page-plugin
+title: Plugins - Correlation ID
+header_title: Correlation ID
+header_icon: /assets/images/icons/plugins/correlation-id.png
+breadcrumbs:
+  Plugins: /plugins
+nav:
+  - label: Getting Started
+    items:
+      - label: Configuration
+  - label: Usage
+    items:
+      - label: Logs
+---
+
+Correlate requests and responses using a unique ID.
+
+----
+
+## Configuration
+
+Configuring the plugin is straightforward. You can associate it with an [API][api-object] by executing the following request to your Kong server:
+
+```bash
+$ curl -X POST http://kong:8001/apis/{api}/plugins \
+    --data "name=correlation-id"
+```
+
+`api`: The `id` or `name` of the API that this plugin configuration will target
+
+form parameter      | required     | description
+---                 | ---          | ---
+`name`              | *required*   | The name of the plugin to use, in this case: `correlation-id`
+`header_name`       | *optional*   | The HTTP header name to use for the correlation ID. Defaults to `Kong-Request-ID`
+`generator  `       | *optional*   | The generator to use for the correlation ID. Accepted values are `uuid` (which generates a UUID for every request), or `uuid#counter` (which generates a UUID once per Nginx worker, and a count for every request). Defaults to `uuid#counter`.
+`echo_downstream`   | *optional*   | Whether to echo the header back to downstream (the API calller). Defaults to `false`.
+
+[api-object]: /docs/latest/admin-api/#api-object
+[configuration]: /docs/latest/configuration
+[consumer-object]: /docs/latest/admin-api/#consumer-object
+[faq-authentication]: /about/faq/#how-can-i-add-an-authentication-layer-on-a-microservice/api?
+
+----
+
+## Logs
+
+The correlation ID will not show up in the Nginx access or error logs. As such, we suggest you use this plugin alongside one of the Logging plugins.