GWAS.tools Logging Specification
This specification defines the structure and categories of events that should be logged in the GWAS ecosystem. Following these standards ensures consistent, comprehensive logging across all GWAS projects and tools.
Log Structure
All logs follow this basic structure:
- timestamp: ISO 8601 datetime (automatically added)
- type: The event type (e.g., git:commit, dev:build)
- source: The source of the log (e.g., gwas.engineer, gwas.app)
- message: A human-readable description of the event
- details: Key-value pairs with additional information
1. Git & GitHub Activities
These events track all interactions with Git repositories and GitHub.
| Event Type | Description | Source | Details to Log |
|---|---|---|---|
| git:commit | Code committed to local repository | gwas.engineer | repo_name, commit_hash, commit_message, files_changed, lines_added, lines_removed, author_name, author_email, assistant_used (if applicable), contribution_split (e.g., ai:80%,human:20%) |
| git:push | Code pushed to remote repository | gwas.engineer | repo_name, branch, commit_count, remote_url |
| git:pull | Code pulled from remote repository | gwas.engineer | repo_name, branch, commit_count, files_changed |
| git:merge | Branches merged | gwas.engineer | repo_name, source_branch, target_branch, conflict_count |
| git:branch | Branch created/deleted | gwas.engineer | repo_name, branch_name, action, from_branch |
| github:pr:open | Pull request opened | gwas.engineer | repo_name, pr_number, title, description, base_branch, head_branch |
| github:pr:merge | Pull request merged | gwas.engineer | repo_name, pr_number, merge_strategy, commit_count |
| github:issue | Issue created/updated | gwas.engineer | repo_name, issue_number, title, action, labels |
2. Development Activities
These events track code creation, editing, and deployment activities.
| Event Type | Description | Source | Details to Log |
|---|---|---|---|
| dev:file:create | New file created | gwas.engineer | file_path, file_type, initial_size, editor, generator (human/ai) |
| dev:file:edit | File edited | gwas.engineer | file_path, lines_changed, editor, edit_duration, generator (human/ai/mixed) |
| dev:build | Project built | gwas.engineer | project_name, build_result, duration, errors, warnings |
| dev:test | Tests run | gwas.engineer | project_name, test_count, passed, failed, skipped, duration |
| dev:deploy | Code deployed | gwas.engineer | environment, service_name, version, deployment_method |
3. AI Assistant Interactions
These events track interactions with AI coding assistants like Cursor, Claude, or GitHub Copilot.
| Event Type | Description | Source | Details to Log |
|---|---|---|---|
| ai:prompt | Query sent to AI | cursor | prompt_length, prompt_topic, model_used, session_id |
| ai:response | Response received from AI | cursor | response_length, response_type (code/text/mixed), execution_time |
| ai:code:generated | Code generated by AI | cursor | file_path, lines_generated, language, prompt_id, acceptance (full/partial/modified) |
| ai:code:edited | Code edited by AI | cursor | file_path, lines_changed, edit_type, prompt_id |
| ai:command:executed | Command suggested and executed | cursor | command, directory, result_code, suggested_by |
Implementation Examples
Example: Logging a commit with AI assistance
deno task gist:log \
--type=git:commit \
--source=gwas.engineer \
--message="Code committed to repository" \
--details="repo_name=gwas-tools,commit_hash=4d6a6ab,commit_message='Add GitHub Gist integration for logs',files_changed=3,lines_added=360,lines_removed=59,author_name=Chan,author_email=chan@example.com,assistant_used=cursor,contribution_split=ai:80%,human:20%"
Example: Logging an AI code generation event
deno task gist:log \
--type=ai:code:generated \
--source=cursor \
--message="AI generated code for log viewer" \
--details="file_path=assets/js/log-viewer.js,lines_generated=320,language=javascript,prompt_id=msg-123,acceptance=full"
Automating Logs with Git Hooks
You can automate logging of Git events using Git hooks. Here's an example post-commit hook that logs commit information and prompts for AI contribution:
#!/bin/bash
# .git/hooks/post-commit
# Get commit information
COMMIT_HASH=$(git rev-parse HEAD)
COMMIT_MSG=$(git log -1 --pretty=%B)
AUTHOR_NAME=$(git log -1 --pretty=%an)
AUTHOR_EMAIL=$(git log -1 --pretty=%ae)
REPO_NAME=$(basename -s .git `git config --get remote.origin.url`)
FILES_CHANGED=$(git diff-tree --no-commit-id --name-only -r HEAD | wc -l)
STATS=$(git diff --stat HEAD~1 HEAD | tail -n 1)
LINES_ADDED=$(echo $STATS | grep -o '[0-9]\+ insertion' | grep -o '[0-9]\+' || echo "0")
LINES_REMOVED=$(echo $STATS | grep -o '[0-9]\+ deletion' | grep -o '[0-9]\+' || echo "0")
# Ask for assistant information
echo "Was an AI assistant used? (y/n)"
read USED_AI
ASSISTANT=""
CONTRIBUTION=""
if [ "$USED_AI" = "y" ]; then
echo "Which assistant? (cursor/claude/github_copilot/other)"
read ASSISTANT
echo "Approximate contribution split? (e.g. ai:60%,human:40%)"
read CONTRIBUTION
fi
# Log the commit
deno task gist:log \
--type=git:commit \
--source=gwas.engineer \
--message="Code committed to repository" \
--details="repo_name=$REPO_NAME,commit_hash=$COMMIT_HASH,commit_message='$COMMIT_MSG',files_changed=$FILES_CHANGED,lines_added=$LINES_ADDED,lines_removed=$LINES_REMOVED,author_name=$AUTHOR_NAME,author_email=$AUTHOR_EMAIL,assistant_used=$ASSISTANT,contribution_split=$CONTRIBUTION"
Visualization Possibilities
With this structured logging data, you can create visualizations like:
- AI vs. human contributions over time
- Most frequently edited files
- Commit patterns by time of day
- Error frequencies during development
- Project activity heatmap