From: Omri Zeneva <ozeneva@redhat.com>
Date: Tue, 24 May 2022 09:08:17 +0000 (-0400)
Subject: doc: add explanation about the new two functions and example
X-Git-Tag: v18.0.0~705^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F46313%2Fhead;p=ceph.git

doc: add explanation about the new two functions and example

Signed-off-by: Omri Zeneva <ozeneva@redhat.com>
---

diff --git a/doc/radosgw/lua-scripting.rst b/doc/radosgw/lua-scripting.rst
index 39268d8aae20..5240f933597b 100644
--- a/doc/radosgw/lua-scripting.rst
+++ b/doc/radosgw/lua-scripting.rst
@@ -320,6 +320,19 @@ during execution so that it may be read and used later during other executions,
 - The maximum number of entries in the table is 100,000. Each entry has a key and string value with a combined length of no more than 1KB. 
   A Lua script will abort with an error if the number of entries or entry size exceeds these limits.
 
+Tracing
+~~~~~~~
+Tracing functions can be used only in `postRequest` context.
+
+- ``Request.Trace.SetAttribute()`` - sets the attribute for the request's trace.
+  Takes two arguments. The first is the `key`, which should be a string. The second is the value, which can either be a string or a number.
+  Using the attribute, you can locate specific traces.
+
+- ``Request.Trace.AddEvent()`` - adds an event to the first span of the request's trace
+  An event is defined by event name, event time, and zero or more event attributes.
+  Therefore, the function accepts one or two arguments. A string containing the event name should be the first argument, followed by the event attributes, which is optional for events without attributes.
+  An event's attributes must be a table of strings.
+
 Lua Code Samples
 ----------------
 - Print information on source and destination objects in case of copy:
@@ -470,3 +483,21 @@ In the `preRequest` context:
 
 Note that changing `Request.Trace.Enable` does not change the tracer's state, but disables or enables the tracing for the request only.
 
+
+- Add Information for requests traces
+
+in `postRequest` context, we can add attributes and events to the request's trace.
+
+.. code-block:: lua
+
+  Request.Trace.AddEvent("lua script execution started")
+
+  Request.Trace.SetAttribute("HTTPStatusCode", Request.Response.HTTPStatusCode)
+
+  event_attrs = {}
+  for k,v in pairs(Request.GenericAttributes) do
+    event_attrs[k] = v
+  end
+
+  Request.Trace.AddEvent("second event", event_attrs)
+