[new] Allow compile-time config of uid kind

taoensso · Sep 6, 2024 · 449c5d4 · 449c5d4
1 parent 2b7cc65
commit 449c5d4
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 27 deletions.
diff --git a/projects/main/src/taoensso/telemere.cljc b/projects/main/src/taoensso/telemere.cljc
@@ -86,39 +86,32 @@
 
 (def ^:dynamic *uid-fn*
   "Experimental, subject to change.
-  (fn [root?]) used to generate signal `:uid` values when tracing.
-  These are basically unique signal instance identifiers.
+  (fn [root?]) used to generate signal `:uid` values (unique instance ids)
+  when tracing.
 
   Relevant only when `otel-tracing?` is false.
   If `otel-tracing?` is true, uids are instead generated by `*otel-tracer*`.
 
-  `root?` argument is true iff signal is a top-level trace (i.e. form
-  being traced is unnested = has no parent form).
+  `root?` argument is true iff signal is a top-level trace (i.e. form being
+  traced is unnested = has no parent form). Root-level uids typically need
+  more entropy and so are usually longer (e.g. 32 vs 16 hex chars).
 
-  Root  uids typically have ~128 bits of entropy to ensure uniqueness.
-  Child uids are typically used only with respect to a parent/root,
-  and so can often make do with ~64 bits of entropy or less.
+  Override default by setting one of the following:
+          JVM property: `taoensso.telemere/uid-fn`
+          Env variable: `TAOENSSO_TELEMERE_UID_FN`
+    Classpath resource: `taoensso.telemere/uid-fn`
 
-  Smaller uids are generally cheaper to generate, and use less space
-  when serializing/transmitting/storing/etc.
+    Possible (compile-time) values include:
+      `:uuid`          - UUID string (Cljs) or `java.util.UUID` (Clj)
+      `:uuid-str`      - UUID string       (36/36 chars)
+      `:nano/secure`   - nano-style string (21/10 chars) w/ strong RNG
+      `:nano/insecure` - nano-style string (21/10 chars) w/ fast   RNG (default)
+      `:hex/insecure`  - hex-style  string (32/16 chars) w/ strong RNG
+      `:hex/secure`    - hex-style  string (32/16 chars) w/ fast   RNG"
 
-  By default generates nano-style uids like
-    \"r76-B8LoIPs5lBG1_Uhdy\" (root) and \"tMEYoZH0K-\" (non-root).
+  (utils/parse-uid-fn impl/uid-kind))
 
-  For plain fixed-length UUIDs        use: (fn [_root?] (utils/uuid))
-  For plain fixed-length UUID strings use: (fn [_root?] (utils/uuid-str))
-
-  See also `utils/nano-uid-fn`, `utils/hex-id-fn`, etc."
-
-  (utils/nano-uid-fn {:secure? false}))
-
-(comment
-  ((utils/nano-uid-fn) true) ; "vdh0bL0YHOXYKWn4sM88e"
-  ((utils/hex-uid-fn)  true) ; "62c0f80d3fb15fb4e356bdd84bae223e"
-  (let [nuid (utils/nano-uid-fn)
-        huid (utils/hex-uid-fn)]
-    (enc/qb 1e6 ; [168.29 21.85 68.6 46.63]
-      (enc/uuid) *uid-fn* (nuid true) (huid true))))
+(comment (enc/qb 1e6 (*uid-fn* true) (*uid-fn* false))) ; [79.4 63.53]
 
 ;;;; OpenTelemetry
 

diff --git a/projects/main/src/taoensso/telemere/impl.cljc b/projects/main/src/taoensso/telemere/impl.cljc
@@ -40,6 +40,11 @@
        (enc/get-env {:as :bool, :default present:otel?}
          :taoensso.telemere/otel-tracing<.platform>))))
 
+(def uid-kind
+  "Documented at `taoensso.telemere/uid-fn`."
+  (enc/get-env {:as :edn, :default :default}
+    :taoensso.telemere/uid-kind<.platform><.edn>))
+
 #?(:clj
    (let [base        (enc/get-env {:as :edn} :taoensso.telemere/ct-filters<.platform><.edn>)
          kind-filter (enc/get-env {:as :edn} :taoensso.telemere/ct-kind-filter<.platform><.edn>)

diff --git a/projects/main/src/taoensso/telemere/utils.cljc b/projects/main/src/taoensso/telemere/utils.cljc
@@ -125,10 +125,44 @@
 
 (comment ((hex-uid-fn) true))
 (comment
-  ;; [170.47 180.18 53.87 60.68]
-  (let [nano-uid-fn (nano-uid-fn), hex-uid-fn (hex-uid-fn)]
+  ;; [168.74 180.83 65.28 47.3]
+  (let [nano-uid (nano-uid-fn), hex-uid (hex-uid-fn)]
     (enc/qb 1e6 (enc/uuid) (enc/uuid-str) (nano-uid true) (hex-uid true))))
 
+(defn ^:no-doc parse-uid-fn
+  "Private, don't use.
+  Returns (fn uid [root?]) for given uid kind."
+  [kind]
+  (case kind
+    :uuid          (fn [_root?] (enc/uuid))
+    :uuid-str      (fn [_root?] (enc/uuid-str))
+    :default       (nano-uid-fn {:secure? false})
+    :nano/insecure (nano-uid-fn {:secure? false})
+    :nano/secure   (nano-uid-fn {:secure? true})
+    :hex/insecure  (hex-uid-fn  {:secure? false})
+    :hex/secure    (hex-uid-fn  {:secure? true})
+
+    (or
+      (when (vector? kind)
+        (let [[kind root-len child-len] kind]
+          (case kind
+            :nano/insecure (nano-uid-fn {:secure? false, :root-len root-len, :child-len child-len})
+            :nano/secure   (nano-uid-fn {:secure? true,  :root-len root-len, :child-len child-len})
+            :hex/insecure  (hex-uid-fn  {:secure? false, :root-len root-len, :child-len child-len})
+            :hex/secure    (hex-uid-fn  {:secure? true,  :root-len root-len, :child-len child-len})
+            nil)))
+
+      (enc/unexpected-arg! kind
+        {:context  `uid-fn
+         :expected
+         '#{:uuid :uuid-str :default,
+            :nano/secure   [:nano/secure   <root-len> <child-len>]
+            :nano/insecure [:nano/insecure <root-len> <child-len>]
+            :hex/secure    [:hex/secure    <root-len> <child-len>]
+            :hex/insecure  [:hex/insecure  <root-len> <child-len>]}}))))
+
+(comment ((parse-uid-fn [:hex/insecure 32 16]) true))
+
 ;;;; Misc
 
 (enc/defaliases