Merge pull request #13 from taskbadger/sk/tags

docs for task tags

Author: snopoke

docs/cli.md

@@ -134,3 +134,13 @@ API Key: XYZ.ABC
 
 Config written to ~/.config/taskbadger/config
 ```
+
+#### Tags
+
+[Tags](data_model.md#tags) can also be added to the configuration file:
+
+```toml
+[tags]
+environment = "production"
+host = "server-1"
+```

docs/data_model.md

@@ -59,6 +59,12 @@ The main attributes or a task are:
 :    This represents the maximum number of seconds allowed between task updates. If a task does not receive
      updates within this period it will be marked as 'stale'.
 
+<a name="tags"></a>
+`tags`
+
+:   A list of tags that can be used to categorize tasks. Tags are useful for filtering tasks in the UI. Each tag
+    has a name and a value. For example, a task may have a tag `environment:production`.
+
 ### Example Task
 
 ```json
@@ -81,7 +87,10 @@ The main attributes or a task are:
   "created": "2022-08-24T14:15:22Z",
   "updated": "2022-08-24T16:15:22Z",
   "url": "https://taskbadger.net/a/{example_org/tasks/57ae8eVBrH7jbDgmYj6Ut2vR9S/",
-  "public_url": "https://taskbadger.net/public/tasks/57ae8eVBrH7jbDgmYj6Ut2vR9S/"
+  "public_url": "https://taskbadger.net/public/tasks/57ae8eVBrH7jbDgmYj6Ut2vR9S/",
+  "tags": [
+    {"environment": "production"}
+  ]
 }
 ```
 

docs/index.md

@@ -17,6 +17,32 @@ In order to use the API you will need the following details:
     * Create one on your Profile page
 
 
+## Montior Celery Tasks
+
+When using the [Celery integration](python-celery.md) you can use the `CelerySystemIntegration` class to automatically record tasks.
+
+```python
+from celery import Celery
+import taskbadger
+from taskbadger.systems.celery import CelerySystemIntegration
+
+app = Celery('hello', broker='amqp://guest@localhost//')
+
+taskbadger.init(
+    organization_slug="my-org",
+    project_slug="my-project",
+    token="***",
+    tags={"environment": "production"},
+    systems=[CelerySystemIntegration(record_task_args=True)]
+)
+
+@app.task
+def hello(who):
+    return f'hello {who}'
+```
+
+This is all the configuration that is needed to do basic task tracking with Celery.
+
 ## Monitor a task from the command line
 
 The Task Badger CLI allows you to run commands from the shell and have them monitored
@@ -41,6 +67,7 @@ Config written to ~/.config/taskbadger/confi
 ```shell
 $ taskbadger run "demo task" \
   --action "error email to:me@test.com" \
+  --tag "environment=staging" \
   -- path/to/script.sh
 
 Task created: https://taskbadger.net/public/tasks/xyz/
@@ -53,8 +80,6 @@ See more about the [CLI](cli.md).
 
 ## Use the API directly
 
-
-
 === "Python"
 
     Install the `taskbadger` Python library:
@@ -71,7 +96,8 @@ See more about the [CLI](cli.md).
     taskbadger.init(
         organization_slug="my-org",
         project_slug="my-project",
-        token="***"
+        token="***",
+        tags={"environment": "production"},
     )
     ```
 
@@ -93,7 +119,7 @@ data.
 === "Python"
 
     ```python
-    > task = Task.create("task name", stale_timeout=10)
+    > task = Task.create("task name", stale_timeout=10, tags={"environment": "staging"})
     > task.id
     "128aoa98e0fiq238"
     ```
@@ -104,7 +130,7 @@ data.
     $ curl -X POST "https://taskbadger.net/api/${ORG}/${PROJECT}/tasks/" \
       -H "Authorization: Bearer ${API_KEY}" \
       -H "Content-Type: application/json" \
-      -d '{"name": "demo task", "stale_timeout": 10}'
+      -d '{"name": "demo task", "stale_timeout": 10, "tags": {"environment": "staging"}}'
     ```
 
     The response will include the task ID which is needed for updating the task.
@@ -127,7 +153,8 @@ data.
       "created": "2022-09-22T06:53:40.683555Z",
       "updated": "2022-09-22T06:53:40.683555Z"
       "url": "https://taskbadger.net/a/{example_org/tasks/{task_id}/",
-      "public_url": "https://taskbadger.net/public/tasks/{task_id}/"
+      "public_url": "https://taskbadger.net/public/tasks/{task_id}/",
+      "tags": {"environment": "staging"}
     }
     ```
 

docs/python-celery.md

@@ -25,7 +25,8 @@ taskbadger.init(
     organization_slug="my-org",
     project_slug="my-project",
     token="***",
-    systems=[CelerySystemIntegration()]
+    systems=[CelerySystemIntegration()],
+    tags={"environment": "production"}
 )
 ```
 

docs/python.md

@@ -20,7 +20,8 @@ import taskbadger
 taskbadger.init(
     organization_slug="my-org",
     project_slug="my-project",
-    token="***"
+    token="***",
+    tags={"environment": "production"},
 )
 ```
 
@@ -29,6 +30,9 @@ Details about these configuration parameters can be found [here](basics.md#organ
 If you attempt to use the SDK without configuring it you will get an error. To avoid this you can use the
 [safe functions](#safe-functions) which will log any errors to the `taskbadger` logger.
 
+!!! tip
+    [Tags](data_model.md#tags) provided here will be applied to all tasks created using the SDK. If you need to add tags to individual tasks you can do so using the create and update methods or the `task.add_tag` method. Tags added manually will override the global tags.
+
 ## Usage
 
 The SDK provides a [Task](#taskbadger.Task) class which offers a convenient interface to the API.
@@ -49,7 +53,8 @@ task = Task.create(
             trigger="*/10%,success,error",
             integration=EmailIntegration(to="me@example.com")
         )
-    ]
+    ],
+    tags={"tenant": "acme"}
 )
 ```
 
@@ -82,16 +87,15 @@ session management is handled automatically within the body of the function or C
 
 ### Scope
 
-The SDK provides the `taskbadger.current_scope` context manager which can be used to set custom data
-for the duration of the context. The content of the scope will be merged with any custom task data
-passed directly to any of the other API methods.
+The SDK provides the `taskbadger.current_scope` context manager which can be used to set custom data and modify tags for the duration of the context. The content of the scope will be merged with any custom task data passed directly to any of the other API methods.
 
 ```python
 import socket
 import taskbadger
 
 with taskbadger.current_scope() as scope:
     scope["hostname"] = socket.gethostname()
+    scope.tag({"tenant": "acme"})
 ```
 
 A common use case for this is to add request scoped context in frameworks like Django or Flask using a custom
@@ -104,6 +108,7 @@ def taskbadger_scope_middleware(get_response):
     def middleware(request):
         with taskbadger.current_scope() as scope:
             scope["user"] = request.user.username
+            scope.tag({"tenant": request.tenant.slug})
             return get_response(request)
 
     return middleware
@@ -113,7 +118,7 @@ def taskbadger_scope_middleware(get_response):
 
     The data passed directly to the API will take precedence over the data in the current scope. If the same
     key is present in the current scope as well as the data passed in directly, the value in the data passed
-    directly will be used.
+    directly will be used. The same applies to tags.
 
 
 ## Python Reference

mkdocs.yml

@@ -98,6 +98,7 @@ plugins:
           separate_signature: True
           members_order: source
           heading_level: 3
+          line_length: 80
 - search:
     separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
 watch:

pyproject.toml

@@ -8,4 +8,5 @@ dependencies = [
     "invoke",
     "mkdocs-material",
     "mkdocstrings[python]",
+    "ruff>=0.9.6",
 ]