Skip to content

Visualize Your Ideas With Code

docs: add logging page (#227)

Tan to the Dashif8ba7154f65f
diff --git a/packages/docs/docs/getting-started/logging.mdx b/packages/docs/docs/getting-started/logging.mdx
new file mode 100644
index 00000000..6aa32324
--- /dev/null
+++ b/packages/docs/docs/getting-started/logging.mdx
@@ -0,0 +1,80 @@
+---
+sidebar_position: 12
+slug: /logging
+---
+
+# Logging
+
+One method of debugging your code or animation flow is using logging messages.
+For this, motion-canvas has its own built-in way to log messages.
+
+To get a reference to the Logger in motion-canvas you can use the `useLogger`
+function:
+
+```tsx
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {useLogger} from '@motion-canvas/core/lib/utils';
+
+export default makeScene2D(function* (view) {
+ const logger = useLogger();
+ // ...
+});
+```
+
+## Basic
+
+Now that we know how to get a reference to the `Logger` we can take a look at
+different ways to log messages. On way is to use standard logging functions like
+`debug`, `info`, `warn` and `error` and simply log a string:
+
+```tsx
+logger.debug('Just here to debug some code.');
+logger.info('All fine just a little info.');
+logger.warn('Be careful somethis has gone wrong.');
+logger.error('Ups. An error occured.');
+```
+
+These messages get then displayed in the UI under the `Console` tab on the left
+side.
+
+## Payloads
+
+In some cases you might want to have a bit more detail in your log messages like
+a `stacktrace` or an `object`. That's where
+[`LogPayloads`](/api/core/index/LogPayload) come in. These can be used to
+provide more information to your log messages.
+
+```ts
+logger.debug({
+ message: 'Some more advanced logging',
+ remarks: 'Some remarks about this log. Can also contain <b>HTML</b> tags.',
+ object: {
+ someProperty: 'some property value',
+ },
+ durationMs: 200,
+ stack: new Error('').stack,
+});
+```
+
+This creates a collapsed log message in the UI which can be expanded to view all
+the details provided.
+
+![](/img/logpayload-message.png)
+
+:::tip
+
+If you quickly want to debug something you can also `debug()`. That way you
+don't have to `useLogger` manually and create a payload.
+
+:::
+
+## Profiling
+
+Besides logging messages its also possible to profile certain sections of code
+with the [`Logger`](/api/core/index/Logger):
+
+```ts
+logger.profile('id'); // <-- starts the profiling
+// some expensive calculation
+logger.profile('id'); // <-- ends the profiling
+```
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
index 8e4dcd37..70d1e501 100644
--- a/packages/docs/docusaurus.config.js
+++ b/packages/docs/docusaurus.config.js
@@ -157,6 +157,10 @@ const config = {
name: 'quickstart',
url: 'Quickstart example',
},
+ {
+ name: 'logging',
+ url: 'Logging example',
+ },
],
},
],
diff --git a/packages/docs/static/img/logpayload-message.png b/packages/docs/static/img/logpayload-message.png
new file mode 100644
index 00000000..cffe9e95
Binary files /dev/null and b/packages/docs/static/img/logpayload-message.png differ
diff --git a/packages/examples/src/logging.meta b/packages/examples/src/logging.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/logging.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/logging.ts b/packages/examples/src/logging.ts
new file mode 100644
index 00000000..be30bdb0
--- /dev/null
+++ b/packages/examples/src/logging.ts
@@ -0,0 +1,7 @@
+import {makeProject} from '@motion-canvas/core';
+
+import scene from './scenes/logging?scene';
+
+export default makeProject({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/scenes/logging.meta b/packages/examples/src/scenes/logging.meta
new file mode 100644
index 00000000..b1593984
--- /dev/null
+++ b/packages/examples/src/scenes/logging.meta
@@ -0,0 +1,18 @@
+{
+ "version": 1,
+ "seed": 1707918003,
+ "timeEvents": [
+ {
+ "name": "basic logging",
+ "targetTime": 0.9814062499999999
+ },
+ {
+ "name": "logging payloads",
+ "targetTime": 1.9671614583333334
+ },
+ {
+ "name": "profiling",
+ "targetTime": 2.985234375
+ }
+ ]
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/logging.tsx b/packages/examples/src/scenes/logging.tsx
new file mode 100644
index 00000000..6a3e37a5
--- /dev/null
+++ b/packages/examples/src/scenes/logging.tsx
@@ -0,0 +1,45 @@
+import {Circle} from '@motion-canvas/2d/lib/components';
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {waitFor, waitUntil} from '@motion-canvas/core/lib/flow';
+import {useLogger} from '@motion-canvas/core/lib/utils';
+
+export default makeScene2D(function* (view) {
+ const logger = useLogger();
+
+ view.add(<Circle key="circle" />);
+
+ // Basic Logging
+ yield* waitUntil('basic logging');
+ logger.debug('Just here to debug some code.');
+ logger.info('All fine, just a little info.');
+ logger.warn('Be careful, something has gone wrong.');
+ logger.error('Oops. An error occured.');
+
+ // Logging Payloads
+ yield* waitUntil('logging payloads');
+
+ logger.debug({
+ message: 'Some more advanced logging',
+ inspect: 'circle',
+ object: {
+ someProperty: 'some property value',
+ },
+ durationMs: 200,
+ remarks: 'Some remarks about this log. Can also contain <b>HTML</b> tags.',
+ stack: new Error('').stack,
+ });
+
+ // Profiling
+ yield* waitUntil('profiling');
+
+ logger.profile('id');
+ yield* waitFor(2);
+ logger.profile('id', {
+ message: 'Id second call',
+ object: {
+ someProperty: 'some property value',
+ },
+ });
+
+ yield* waitFor(2);
+});
diff --git a/packages/examples/vite.config.ts b/packages/examples/vite.config.ts
index 3948aceb..51f80336 100644
--- a/packages/examples/vite.config.ts
+++ b/packages/examples/vite.config.ts
@@ -21,6 +21,7 @@ export default defineConfig({
'./src/media-image.ts',
'./src/media-video.ts',
'./src/components.ts',
+ './src/logging.ts',
],
}),
],