From 29c0eba6e4a3052f6c9f6ac87c3eaa4c6627cd1b Mon Sep 17 00:00:00 2001 From: Daniel <101145494+dan-jan@users.noreply.github.com> Date: Fri, 3 Nov 2023 16:13:32 +0700 Subject: [PATCH 1/2] Migrate ADRs to Specs --- adr/Makefile | 14 --- adr/adr-template.md | 31 ------ specs/Makefile | 14 +++ {adr => specs}/README.md | 5 +- .../adr-001-jan-deployable-cloud-native.md | 0 {adr => specs}/adr-002-jan-ai-apps.md | 0 {adr => specs}/adr-003-jan-plugins.md | 0 {adr => specs}/adr-004-UI-Service.md | 0 {adr => specs}/adr-005-model-installation.md | 0 {adr => specs}/adr-006-jan-core-module.md | 0 {adr => specs}/adr-007-jan-plugin-catalog.md | 0 .../adr-008-Extensible-Jan-with-Docker.md | 0 {adr => specs}/images/adr-001-01.png | Bin {adr => specs}/images/adr-001-02.png | Bin {adr => specs}/images/adr-002-01.png | Bin {adr => specs}/images/adr-002-02.png | Bin {adr => specs}/images/adr-003-01.png | Bin {adr => specs}/images/jan-core-module.png | Bin {adr => specs}/images/jan-plugin-catalog.png | Bin {adr => specs}/images/jan-ui-framework.png | Bin specs/jan-001-log-framework.md | 101 ++++++++++++++++++ specs/spec-template.md | 33 ++++++ 22 files changed, 151 insertions(+), 47 deletions(-) delete mode 100644 adr/Makefile delete mode 100644 adr/adr-template.md create mode 100644 specs/Makefile rename {adr => specs}/README.md (63%) rename {adr => specs}/adr-001-jan-deployable-cloud-native.md (100%) rename {adr => specs}/adr-002-jan-ai-apps.md (100%) rename {adr => specs}/adr-003-jan-plugins.md (100%) rename {adr => specs}/adr-004-UI-Service.md (100%) rename {adr => specs}/adr-005-model-installation.md (100%) rename {adr => specs}/adr-006-jan-core-module.md (100%) rename {adr => specs}/adr-007-jan-plugin-catalog.md (100%) rename {adr => specs}/adr-008-Extensible-Jan-with-Docker.md (100%) rename {adr => specs}/images/adr-001-01.png (100%) rename {adr => specs}/images/adr-001-02.png (100%) rename {adr => specs}/images/adr-002-01.png (100%) rename {adr => specs}/images/adr-002-02.png (100%) rename {adr => specs}/images/adr-003-01.png (100%) rename {adr => specs}/images/jan-core-module.png (100%) rename {adr => specs}/images/jan-plugin-catalog.png (100%) rename {adr => specs}/images/jan-ui-framework.png (100%) create mode 100644 specs/jan-001-log-framework.md create mode 100644 specs/spec-template.md diff --git a/adr/Makefile b/adr/Makefile deleted file mode 100644 index edbe801ea..000000000 --- a/adr/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -newadr: - @echo "Initiating an ADR..." - @last_number=$$(ls $(CURDIR)/adr-[0-9][0-9][0-9]-* | sort -V | tail -n 1 | cut -d '-' -f 2); \ - last_number=$$(echo $$last_number | sed 's/^0*//'); \ - next_number=$$(printf "%03d" $$(( $$last_number + 1 ))); \ - read -p "Enter ADR title: " title; \ - title=$$(echo $$title | tr ' ' '-'); \ - cp $(CURDIR)/adr-template.md $(CURDIR)/adr-$$next_number-$$title.md; \ - date=$$(date +%Y-%m-%d); \ - usernames=$$(git config user.name); \ - sed -i '' 's/{ADR-NUM}/'$$next_number'/g' $(CURDIR)/adr-$$next_number-$$title.md; \ - sed -i '' 's/{TITLE}/'$$title'/g' $(CURDIR)/adr-$$next_number-$$title.md; \ - sed -i '' 's/{DATE}/'$$date'/g' $(CURDIR)/adr-$$next_number-$$title.md; \ - sed -i '' 's/{USERNAMES}/'$$usernames'/g' $(CURDIR)/adr-$$next_number-$$title.md \ No newline at end of file diff --git a/adr/adr-template.md b/adr/adr-template.md deleted file mode 100644 index 61e14f928..000000000 --- a/adr/adr-template.md +++ /dev/null @@ -1,31 +0,0 @@ -# ADR {ADR-NUM}: {TITLE} - -## Changelog - -- {DATE}: Initial draft - -## Authors - -- {USERNAMES} - -## Status - -What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? - -{Proposed|Accepted|Rejected} - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## Alternatives - -## Reference diff --git a/specs/Makefile b/specs/Makefile new file mode 100644 index 000000000..4646dfdcd --- /dev/null +++ b/specs/Makefile @@ -0,0 +1,14 @@ +spec: + @echo "Initiating a Spec..." + @last_number=$$(ls $(CURDIR)/jan-[0-9][0-9][0-9]-* | sort -V | tail -n 1 | cut -d '-' -f 2); \ + last_number=$$(echo $$last_number | sed 's/^0*//'); \ + next_number=$$(printf "%03d" $$(( $$last_number + 1 ))); \ + read -p "Enter Spec title: " title; \ + title=$$(echo $$title | tr ' ' '-'); \ + cp $(CURDIR)/spec-template.md $(CURDIR)/jan-$$next_number-$$title.md; \ + date=$$(date +%Y-%m-%d); \ + usernames=$$(git config user.name); \ + sed -i '' 's/{SPEC-NUM}/'$$next_number'/g' $(CURDIR)/jan-$$next_number-$$title.md; \ + sed -i '' 's/{TITLE}/'$$title'/g' $(CURDIR)/jan-$$next_number-$$title.md; \ + sed -i '' 's/{DATE}/'$$date'/g' $(CURDIR)/jan-$$next_number-$$title.md; \ + sed -i '' 's/{USERNAMES}/'$$usernames'/g' $(CURDIR)/jan-$$next_number-$$title.md \ No newline at end of file diff --git a/adr/README.md b/specs/README.md similarity index 63% rename from adr/README.md rename to specs/README.md index ae6691594..25b342ef5 100644 --- a/adr/README.md +++ b/specs/README.md @@ -1,7 +1,8 @@ -# Architectural Decision Records (ADR) +# Jan Improvement Proposals -This is a repo of key architecture decisions for Jan. [Read more about ADRs](https://github.com/joelparkerhenderson/architecture-decision-record) +This is a repo of key architecture decisions for Jan. +[Read more about ADRs](https://github.com/joelparkerhenderson/architecture-decision-record) ### Get started: diff --git a/adr/adr-001-jan-deployable-cloud-native.md b/specs/adr-001-jan-deployable-cloud-native.md similarity index 100% rename from adr/adr-001-jan-deployable-cloud-native.md rename to specs/adr-001-jan-deployable-cloud-native.md diff --git a/adr/adr-002-jan-ai-apps.md b/specs/adr-002-jan-ai-apps.md similarity index 100% rename from adr/adr-002-jan-ai-apps.md rename to specs/adr-002-jan-ai-apps.md diff --git a/adr/adr-003-jan-plugins.md b/specs/adr-003-jan-plugins.md similarity index 100% rename from adr/adr-003-jan-plugins.md rename to specs/adr-003-jan-plugins.md diff --git a/adr/adr-004-UI-Service.md b/specs/adr-004-UI-Service.md similarity index 100% rename from adr/adr-004-UI-Service.md rename to specs/adr-004-UI-Service.md diff --git a/adr/adr-005-model-installation.md b/specs/adr-005-model-installation.md similarity index 100% rename from adr/adr-005-model-installation.md rename to specs/adr-005-model-installation.md diff --git a/adr/adr-006-jan-core-module.md b/specs/adr-006-jan-core-module.md similarity index 100% rename from adr/adr-006-jan-core-module.md rename to specs/adr-006-jan-core-module.md diff --git a/adr/adr-007-jan-plugin-catalog.md b/specs/adr-007-jan-plugin-catalog.md similarity index 100% rename from adr/adr-007-jan-plugin-catalog.md rename to specs/adr-007-jan-plugin-catalog.md diff --git a/adr/adr-008-Extensible-Jan-with-Docker.md b/specs/adr-008-Extensible-Jan-with-Docker.md similarity index 100% rename from adr/adr-008-Extensible-Jan-with-Docker.md rename to specs/adr-008-Extensible-Jan-with-Docker.md diff --git a/adr/images/adr-001-01.png b/specs/images/adr-001-01.png similarity index 100% rename from adr/images/adr-001-01.png rename to specs/images/adr-001-01.png diff --git a/adr/images/adr-001-02.png b/specs/images/adr-001-02.png similarity index 100% rename from adr/images/adr-001-02.png rename to specs/images/adr-001-02.png diff --git a/adr/images/adr-002-01.png b/specs/images/adr-002-01.png similarity index 100% rename from adr/images/adr-002-01.png rename to specs/images/adr-002-01.png diff --git a/adr/images/adr-002-02.png b/specs/images/adr-002-02.png similarity index 100% rename from adr/images/adr-002-02.png rename to specs/images/adr-002-02.png diff --git a/adr/images/adr-003-01.png b/specs/images/adr-003-01.png similarity index 100% rename from adr/images/adr-003-01.png rename to specs/images/adr-003-01.png diff --git a/adr/images/jan-core-module.png b/specs/images/jan-core-module.png similarity index 100% rename from adr/images/jan-core-module.png rename to specs/images/jan-core-module.png diff --git a/adr/images/jan-plugin-catalog.png b/specs/images/jan-plugin-catalog.png similarity index 100% rename from adr/images/jan-plugin-catalog.png rename to specs/images/jan-plugin-catalog.png diff --git a/adr/images/jan-ui-framework.png b/specs/images/jan-ui-framework.png similarity index 100% rename from adr/images/jan-ui-framework.png rename to specs/images/jan-ui-framework.png diff --git a/specs/jan-001-log-framework.md b/specs/jan-001-log-framework.md new file mode 100644 index 000000000..5af88d423 --- /dev/null +++ b/specs/jan-001-log-framework.md @@ -0,0 +1,101 @@ +# jan-001: Application Logs Framework + +| Proposal | jan-001 | +| ---------- | ----------------------------------------------------- | +| Title | App Logging | +| Authors | @louis-jan | +| Permalink | | +| Discussion | [issue #528](https://github.com/janhq/jan/issues/528) | +| Status | Idea | + +## Changelog + +| Date | Author | Changes | +| ------------ | ---------- | ------------- | +| Nov 2nd 2023 | @louis-jan | Initial Draft | + +## Summary + +This proposal suggests the implementation of an "App logging as file and log window" feature, which aims to address the problem of limited visibility into the operation of a production application. Currently, logs (info, verbose, error) are hidden, making it challenging for both users and developers to debug and support the application. The proposed solution involves logging application-wide activities to a file while also enabling real-time log monitoring through a dedicated log window within the application. + +## Motivation + +### Problem Description +The lack of proper logging in production applications results in several challenges: + +1. Debugging Difficulty: When an issue arises in a production environment, developers have limited access to essential information about what happened, making it challenging to diagnose and resolve problems effectively. +2. Support Challenges: Users often encounter errors or unexpected behavior, and support teams struggle to gather the necessary logs to understand the issue and provide a solution promptly. +3. Lack of Real-time Insights: Real-time monitoring is essential for identifying and responding to critical events. The absence of a log window within the application prevents timely reactions to events. + +### Use Case Example +Consider an e-commerce application. In the current state, when a user faces an issue during checkout, there's no easy way for support or development teams to see what went wrong in real time. This results in frustration for the user and a loss of business for the company + +```ts +# Current Status (Without the Feature) +try: + # Checkout logic + # ... +except Exception as e: + # Error handling + console.log(err) + # Insufficient logging +``` + +Without proper logging, it is challenging to diagnose the issue and provide immediate assistance. + +## Proposed solution + +### High-level overview +The proposed solution introduces the following key changes: + +1. Application-wide Logging: Implement a logging mechanism that logs application-wide activities to a designated log file. This ensures that all relevant information is captured for later analysis and debugging. +2. Real-time Log Window: Create a log window within the application that displays log entries in real time. Users and developers can open this window to monitor logs, allowing them to react promptly to events and errors. + +```ts +# With the Proposed Feature +try: + # Checkout logic + # ... +except Exception as e: + # Error handling + log.error(f"Error when downloading model: {e}") + # Proper logging + +``` + +![Image](https://github.com/janhq/jan/assets/133622055/b60f6976-8138-438e-aa4f-7e103037e124) + + +### Specification + +- The logging system will support different log levels (e.g., info, verbose, error) to ensure that the right level of detail is captured. +- Log entries will be timestamped and categorized to aid in the analysis and debugging process. +- The log window will provide options for filtering and searching log entries for ease of use. + + +### Compatibility + +This proposal aims to preserve backward compatibility by ensuring that the new logging system does not break existing functionality or affect existing applications negatively. It should not alter the semantics of valid programs. + + +### Other concerns + +- Implementation: Careful consideration should be given to the choice of logging framework and implementation details. +- Security: Access to logs and log window functionality should be restricted to authorized users to prevent potential security risks. + +### Open questions + +- What will be the default log file location, and how will it be configurable? +- Should log entries be persisted and rotated over time to prevent excessive file size? + +## Alternatives + +Alternative approaches may involve integrating with existing third-party logging systems or cloud-based log management platforms. However, this proposal focuses on a built-in solution for application-wide logging and real-time monitoring. + +## Related work + +This proposal is inspired by similar features in various application development frameworks and tools. + +## FAQ + +No frequently asked questions at this time. \ No newline at end of file diff --git a/specs/spec-template.md b/specs/spec-template.md new file mode 100644 index 000000000..32929affb --- /dev/null +++ b/specs/spec-template.md @@ -0,0 +1,33 @@ +# jan-{SPEC-NUM}: {TITLE} + +| Proposal | jan-{SPEC-NUM} | +| ---------- | -------------- | +| Title | {TITLE} | +| Authors | | +| Permalink | | +| Discussion | | +| Status | Idea | + +## Changelog + +| Date | Author | Changes | +| ---- | ------ | ------------- | +| | | Initial Draft | + +## Abstract + +Summary. Please keep it very short. + +## Motivation + +Why? + +## Specification + +What, how? +- UX Mockups +- Code Interfaces + +## Appendix + +Everything else goes here. \ No newline at end of file From 0c13067420a86c9bf777125caa373bba94c2f5ef Mon Sep 17 00:00:00 2001 From: Daniel <101145494+dan-jan@users.noreply.github.com> Date: Fri, 3 Nov 2023 16:15:54 +0700 Subject: [PATCH 2/2] Migrate ADRs to specs --- specs/{ => adrs}/adr-001-jan-deployable-cloud-native.md | 0 specs/{ => adrs}/adr-002-jan-ai-apps.md | 0 specs/{ => adrs}/adr-003-jan-plugins.md | 0 specs/{ => adrs}/adr-004-UI-Service.md | 0 specs/{ => adrs}/adr-005-model-installation.md | 0 specs/{ => adrs}/adr-006-jan-core-module.md | 0 specs/{ => adrs}/adr-007-jan-plugin-catalog.md | 0 specs/{ => adrs}/adr-008-Extensible-Jan-with-Docker.md | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename specs/{ => adrs}/adr-001-jan-deployable-cloud-native.md (100%) rename specs/{ => adrs}/adr-002-jan-ai-apps.md (100%) rename specs/{ => adrs}/adr-003-jan-plugins.md (100%) rename specs/{ => adrs}/adr-004-UI-Service.md (100%) rename specs/{ => adrs}/adr-005-model-installation.md (100%) rename specs/{ => adrs}/adr-006-jan-core-module.md (100%) rename specs/{ => adrs}/adr-007-jan-plugin-catalog.md (100%) rename specs/{ => adrs}/adr-008-Extensible-Jan-with-Docker.md (100%) diff --git a/specs/adr-001-jan-deployable-cloud-native.md b/specs/adrs/adr-001-jan-deployable-cloud-native.md similarity index 100% rename from specs/adr-001-jan-deployable-cloud-native.md rename to specs/adrs/adr-001-jan-deployable-cloud-native.md diff --git a/specs/adr-002-jan-ai-apps.md b/specs/adrs/adr-002-jan-ai-apps.md similarity index 100% rename from specs/adr-002-jan-ai-apps.md rename to specs/adrs/adr-002-jan-ai-apps.md diff --git a/specs/adr-003-jan-plugins.md b/specs/adrs/adr-003-jan-plugins.md similarity index 100% rename from specs/adr-003-jan-plugins.md rename to specs/adrs/adr-003-jan-plugins.md diff --git a/specs/adr-004-UI-Service.md b/specs/adrs/adr-004-UI-Service.md similarity index 100% rename from specs/adr-004-UI-Service.md rename to specs/adrs/adr-004-UI-Service.md diff --git a/specs/adr-005-model-installation.md b/specs/adrs/adr-005-model-installation.md similarity index 100% rename from specs/adr-005-model-installation.md rename to specs/adrs/adr-005-model-installation.md diff --git a/specs/adr-006-jan-core-module.md b/specs/adrs/adr-006-jan-core-module.md similarity index 100% rename from specs/adr-006-jan-core-module.md rename to specs/adrs/adr-006-jan-core-module.md diff --git a/specs/adr-007-jan-plugin-catalog.md b/specs/adrs/adr-007-jan-plugin-catalog.md similarity index 100% rename from specs/adr-007-jan-plugin-catalog.md rename to specs/adrs/adr-007-jan-plugin-catalog.md diff --git a/specs/adr-008-Extensible-Jan-with-Docker.md b/specs/adrs/adr-008-Extensible-Jan-with-Docker.md similarity index 100% rename from specs/adr-008-Extensible-Jan-with-Docker.md rename to specs/adrs/adr-008-Extensible-Jan-with-Docker.md