Skip to content

Commit 2c4f1a1

Browse files
satyakighsatyakigh
authored
Update readmes (#214)
1 parent 51440ba commit 2c4f1a1

File tree

2 files changed

+65
-62
lines changed

2 files changed

+65
-62
lines changed

‎README.md‎

Lines changed: 43 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# AWS CloudFormation Language Server for Code Editors
1+
# AWS CloudFormation Language Server
22

33
<div align="center">
44

@@ -8,50 +8,61 @@
88

99
</div>
1010

11-
A LSP server implementation that provides intelligent editing support for CloudFormation templates in JSON and YAML formats.
11+
The AWS CloudFormation Language Server provides auto-completion, validation, navigation, and refactoring for CloudFormation templates.
12+
The server implements the Language Server Protocol (LSP) to enable code editors to offer intelligent editing support for JSON and YAML Infrastructure as Code templates.
1213

1314
## Features
1415

15-
### Intelligent Code Completion
16-
- **Resource Types**: Auto-complete AWS resource types with fuzzy matching
17-
- **Properties**: Context-aware property suggestions for CloudFormation resources
18-
- **Intrinsic Functions**: Complete function names and parameter suggestions
19-
- **Parameters & References**: Auto-complete template parameters, conditions, and mappings
20-
- **Template Sections**: Top-level CloudFormation section completion
21-
22-
### Real-time Validation
23-
- **Syntax Validation**: Immediate feedback on JSON/YAML syntax errors
24-
- **Schema Validation**: CloudFormation resource schema enforcement with regional support
25-
- **cfn-lint Integration**: Python-based linting with comprehensive rule validation
26-
- **AWS Guard Integration**: Policy-as-code validation for security and compliance
16+
### Code Completion
17+
- **Resource Types** - Auto-completes AWS resource types with fuzzy matching
18+
- **Properties** - Context-aware property suggestions for CloudFormation resources
19+
- **Intrinsic Functions** - Function names and parameter suggestions
20+
- **Parameters & References** - Template parameters, conditions, and mappings
21+
- **Template Sections** - Top-level CloudFormation sections
22+
23+
### Validation
24+
- **Syntax** - Immediate feedback on JSON and YAML syntax errors
25+
- **Schema** - CloudFormation resource schema enforcement with regional support
26+
- **cfn-lint** - Python-based linting with comprehensive rules
27+
- **AWS Guard** - Policy-as-code validation for security and compliance
28+
29+
### Code Actions & Refactoring
30+
- **Quick Fixes** - Fixes for common template errors
31+
- **Extract to Parameter** - Refactors hardcoded values into template parameters
32+
- **Related Resources** - Inserts related AWS resources based on template context
33+
- **Diagnostic Actions** - Actionable suggestions for validation errors
2734

2835
### Documentation & Navigation
29-
- **Hover Documentation**: Contextual help for resources, properties, and functions
30-
- **Go-to-Definition**: Navigate to CloudFormation reference definitions
31-
- **Document Symbols**: Template structure navigation and outline view
32-
- **Parameter Information**: Type and constraint documentation
36+
- **Hover Documentation** - Contextual help for resources, properties, and functions
37+
- **Go-to-Definition** - Navigate to CloudFormation reference definitions
38+
- **Document Symbols** - Template structure navigation and outline view
39+
- **Parameter Information** - Type and constraint documentation
3340

3441
### AWS Integration
35-
- **Stack Operations**: List and manage CloudFormation stacks
36-
- **Resource Discovery**: Browse available AWS resource types by region
37-
- **Template Validation**: Server-side CloudFormation template validation
38-
- **Template Deployment**: Deploy templates directly from the editor
39-
- **Resource State Import**: Import existing AWS resources into templates
42+
- **Stack Operations** - List and manage CloudFormation stacks
43+
- **Resource Discovery** - Browse available AWS resource types by region
44+
- **Template Validation** - Server-side template validation using CloudFormation
45+
- **Template Deployment** - Deploy templates directly from the editor
46+
- **Resource State Import** - Import existing AWS resources into templates
47+
- **Clone Resource** - Create new resources using existing resource configurations as reference
48+
- **IaC Generator** - Scan AWS accounts and generate CloudFormation templates from existing resources
49+
- **Artifact Export** - Export and upload template artifacts to S3 for deployment
50+
51+
### Code Lens Actions
52+
- **Validate Deployment** - Validate template deployment from the editor
53+
- **Deploy Template** - Deploy templates with a single click
54+
- **Open Stack Template** - Open managed stack templates for resources
4055

4156
### Advanced Capabilities
42-
- **Multi-Format Support**: Native JSON and YAML CloudFormation template processing
43-
- **Partial Parsing**: Intelligent completion even in incomplete or malformed templates
44-
- **Regional Schemas**: Automatic schema retrieval and caching for different AWS regions
45-
46-
## Requirements
47-
48-
- **Node.js**: Version 22.15.0 to 22.17.0
49-
- **npm**: Version 10.5.0 or higher
57+
- **Multi-Format Support** - JSON and YAML CloudFormation template processing
58+
- **Partial Parsing** - Completion in incomplete or malformed templates
59+
- **Regional Schemas** - Automatic schema retrieval and caching for different AWS regions
60+
- **Tree-sitter Parsing** - Fast and accurate syntax parsing
5061

5162
## Telemetry
5263

5364
The CloudFormation Language Server collects anonymous usage metrics. See [Telemetry](src/telemetry/README.md) for details on what is collected and how to control telemetry settings.
5465

5566
## License
5667

57-
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
68+
This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

‎src/telemetry/README.md‎

Lines changed: 22 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,28 @@
11
# Telemetry
22

3-
## Why We Collect Telemetry
3+
The CloudFormation Language Server collects anonymous usage metrics (telemetry) using OpenTelemetry, the industry-standard observability framework, to measure and maintain real-time performance.
4+
Language servers must deliver suggestions quickly to avoid interrupting your workflow.
45

5-
The CloudFormation Language Server collects anonymous usage metrics using OpenTelemetry, the industry-standard observability framework, to ensure we provide a near real-time experience. Language servers must deliver suggestions quickly and accurately to avoid interrupting your workflow. These metrics help us:
6-
7-
* Measure response times for autocomplete, validation, and hover documentation
8-
* Understand the quality and relevance of suggestions we provide
9-
* Detect performance degradation that impacts your editing experience
10-
* Identify errors that prevent features from working correctly
11-
12-
Without telemetry, we cannot determine if suggestions appear fast enough or if the language server is meeting the performance expectations of a real-time editing experience.
6+
Telemetry enablement is controlled by your LSP client via initialization options passed to the language server, see [Enable or Disable Telemetry](#enable-or-disable-telemetry) for details.
7+
The CloudFormation Language Server environment you use will determine the default telemetry collection behaviour:
8+
* Alpha - Telemetry is enabled by default if no initialization parameter is provided
9+
* Beta and Prod - Telemetry is disabled by default if no initialization parameter is provided
1310

1411
## What We Collect
12+
Language servers must deliver suggestions quickly and accurately to avoid interrupting your workflow. These metrics help us:
13+
* Measure response time: How long an operation took to complete (hover, autocomplete, go-to, etc.)
14+
* Understand the quality and relevance of suggestions we provide
15+
* Usage metrics: Invocation counts for operations
16+
* Error metrics: Fault counts when operations fail
17+
* Response metrics: Type and size of data returned by operations
18+
* Primitive data types only, actual data is not recorded
19+
* System Information: Operating system, LSP client version, Node.js version
20+
* Does the hardware impact customer experience?
21+
* Detect performance degradations that impacts the authoring experience
1522

16-
We collect anonymous operational metrics including:
17-
18-
* **Performance data**: Response times for autocomplete, validation, and hover documentation (in milliseconds)
19-
* **Usage counts**: Number of times you use specific features
20-
* **Error information**: Exception types and volume
21-
* **System information**: Operating system type, LSP client version, Node.js version
22-
* **Session identifier**: A unique ID that tracks your session without identifying you personally
23+
Without telemetry, we cannot objectively evaluate if suggestions are accurate or if the language server is meeting the performance expectations of a real-time authoring experience.
2324

2425
### Metrics Metadata
25-
2626
Every metric includes the following metadata attributes:
2727

2828
| Attribute | Description | Example |
@@ -36,16 +36,11 @@ Every metric includes the following metadata attributes:
3636
| `process.version` | Node.js and V8 versions | `node=22.18.0 v8=12.4.254.21-node.27 uv=1.51.0 modules=127` |
3737
| `OTelLib` | Operation name | `Hover`, `AutoComplete`, etc. |
3838

39-
## How Data is Transmitted
40-
41-
* Metrics export every 30 seconds via HTTPS with TLS 1.2+ encryption
42-
* Data is sent using the OpenTelemetry Protocol (OTLP) over HTTP
43-
44-
## How to Enable or Disable Telemetry
39+
## Data Transmission
40+
Metrics export every 30 seconds via HTTPS with TLS 1.2+ encryption using OpenTelemetry Protocol (OTLP).
4541

46-
Telemetry is controlled by your LSP client via extend initialization options passed to the language server:
47-
48-
For example,
42+
## Enable or Disable Telemetry
43+
Your LSP client (AWS ToolKit, VSCode, JetBrains, etc.) controls telemetry enablement via initialization options. For example:
4944
```
5045
...
5146
initializationOptions: {
@@ -59,7 +54,4 @@ initializationOptions: {
5954
...
6055
```
6156

62-
Your LSP client controls telemetry settings. Consult your LSP client's documentation for configuration options. Changes require restarting the language server to take effect.
63-
64-
* **Alpha environment**: Telemetry is enabled by default if no initialization parameter is provided
65-
* **Beta and Production environments**: Telemetry is disabled by default if no initialization parameter is provided
57+
Consult your LSP client's documentation for configuration options. Changes to telemetry enablement require restarting the language server to take effect.

0 commit comments

Comments
 (0)