diff --git a/src/libDiagnosticMessagesClient/include/msgtracer_client.h b/src/libDiagnosticMessagesClient/include/msgtracer_client.h
index 44cb7d294..600933430 100644
--- a/src/libDiagnosticMessagesClient/include/msgtracer_client.h
+++ b/src/libDiagnosticMessagesClient/include/msgtracer_client.h
@@ -3,6 +3,19 @@
 
 #include <asl.h>
 
-extern void msgtracer_log_with_keys(char *key1, int value1, char *things, ...);
+/**
+ * how it seems to be used:
+ *   msgtracer_log_with_keys(
+ *     "message.id.here", // usually the bundle id of the caller plus some arbitrary message name
+ *     ASL_LEVEL_<something>, // one of the asl log levels in `asl.h`
+ *     // the rest of the arguments are just pairs of arguments
+ *     // the pairs go a little something like this:
+ *     kMsgTracerKey<some-key-name>, // one of the keys in `msgtracer_keys.h`
+ *     <some-c-string-value> // value for the provided key
+ *     ... // as many of those pairs as you want
+ *     NULL // and finally you terminate it with `NULL` so the function knows where the arguments end
+ *   )
+ */
+extern void msgtracer_log_with_keys(char* logger_id, int log_level, ...);
 
 #endif
diff --git a/src/libDiagnosticMessagesClient/include/msgtracer_keys.h b/src/libDiagnosticMessagesClient/include/msgtracer_keys.h
new file mode 100644
index 000000000..14cde44f5
--- /dev/null
+++ b/src/libDiagnosticMessagesClient/include/msgtracer_keys.h
@@ -0,0 +1,19 @@
+#ifndef __MSGTRACER_KEYS_H__
+#define __MSGTRACER_KEYS_H__
+
+// from:
+//   `Security/OSX/libsecurity_ssl/Security/sslTransport.c`
+//   `Security/securityd/src/token.cpp`
+//   `IOKitUser/hidsystem.subproj/IOHIDLib.c`
+// plus a little bit of common sense ;)
+//
+// once again, i am amazed at Apple's failure to properly hide things
+#define kMsgTracerKeySignature "com.apple.message.signature"
+#define kMsgTracerKeySummarize "com.apple.message.summarize"
+#define kMsgTracerKeySignature2 "com.apple.message.signature2"
+
+// these are good guesses
+#define kMsgTracerKeyValue "com.apple.message.value"
+#define kMsgTracerKeyValue2 "com.apple.message.value2"
+
+#endif // __MSGTRACER_KEYS_H__