Add dotted_order comment (#440)

versioned_docs/version-2.0/how_to_guides/tracing/trace_with_api.mdx

@@ -83,3 +83,5 @@ chat_completion = client.chat.completions.create(model="gpt-3.5-turbo", messages
 patch_run(child_run_id, chat_completion.dict())
 patch_run(parent_run_id, {"answer": chat_completion.choices[0].message.content})
 ```
+
+See the doc on the [Run (span) data format](../../reference/data_formats/run_data_format) for more information.

versioned_docs/version-2.0/reference/data_formats/run_data_format.mdx

@@ -30,7 +30,7 @@ The **bolded** fields are the most important ones to know about.
 | **events**                   | array of objects | A list of event objects associated with the run. This is relevant for runs executed with streaming.            |
 | **tags**                     | array of strings | Tags or labels associated with the run.                                                                        |
 | **trace_id**                 | UUID             | Unique identifier for the trace the run is a part of. This is also the `id` field of the root run of the trace |
-| **dotted_order**             | string           | Custom ordering string, hierarchical. Built with timestamp and unique identifiers.                             |
+| **dotted_order**             | string           | Ordering string, hierarchical. Format: <run_start_time>Z<run_uuid>.<child_run_start_time>Z<child_run_uuid>...  |
 | **status**                   | string           | Current status of the run execution, e.g., "error", "pending", "success"                                       |
 | **child_run_ids**            | array of UUIDs   | List of IDs for all child runs.                                                                                |
 | **direct_child_run_ids**     | array of UUIDs   | List of IDs for direct children of this run.                                                                   |
@@ -108,3 +108,55 @@ Here is an example of a JSON representation of a run in the above format:
   "share_token": "d0430ac3-04a1-4e32-a7ea-57776ad22c1c"
 }
 ```
+
+#### What is `dotted_order`?
+
+A run's dotted order is a sortable key that fully specifies its location within the tracing hierarchy.
+
+Take the following example:
+
+```python
+import langsmith as ls
+
+
+@ls.traceable
+def grandchild():
+    p("grandchild")
+
+
+@ls.traceable
+def child():
+    grandchild()
+
+
+@ls.traceable
+def parent():
+    child()
+```
+
+If you print out the IDs at each stage, you may get the following:
+
+```text
+parent
+	run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7
+	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7
+  parent_run_id=null
+	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7
+child
+	run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097
+	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7
+  parent_run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7
+	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097
+grandchild
+	run_id=0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6
+	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7
+  parent_run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097
+	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097.20240919T171648523563Z0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6
+```
+
+Note a few invariants:
+
+- The "id" is equal to the last 36 characters of the dotted order (the suffix after the final "Z"). See `0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6` for example in the grandchild.
+- The "trace_id" is equal to the first UUID in the dotted order (i.e., `dotted_order.split('.')[0].split('Z')[1]`)
+- If "parent_run_id" exists, it is the penultimate UUID in the dotted order. See `a8024e23-5b82-47fd-970e-f6a5ba3f5097` in the grandchild, for an example.
+- If you split the dotted_order on the dots, each segment is formatted as (`<run_start_time>Z<run_id>`)