Skip to content

Commit

Permalink
Update README.md (#44)
Browse files Browse the repository at this point in the history 
* update docs
  • Loading branch information
@joeldickson
joeldickson authored Sep 13, 2024
1 parent 030ee79 commit 4050870
Show file tree
Hide file tree
Showing 4 changed files with 205 additions and 39 deletions.
77 changes: 77 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Contributing to Dotnet Build and Test Metrics

First off, thanks for taking the time to contribute! You're already faster than an unoptimized build! 🚀

## The Zen of Dotnet Metrics

```
Fast is better than slow.
Measured is better than guessed.
Simple is better than complex.
Complex is better than complicated.
Flat hierarchies are better than nested ones.
Sparse matrices are better than dense ones.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're a C# ninja.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's probably too slow.
If the implementation is easy to explain, it may be fast enough.
Namespaces are one honking great idea -- let's do more of those!
```

## Project Structure

This project is a monorepo containing tools for build metrics, startup metrics, and test metrics for both NUnit and xUnit. They're all here because we believe in the "one repo to rule them all" philosophy (and because it's just more convenient that way).

## The F5 Experience

Remember, we're all about that F5 Experience here. Our goal is to make the development process smoother than a baby's bottom. Here's what that means for contributors:

1. **Setup Should Be a Breeze**: You should be able to clone the repo and get up and running faster than you can say "dotnet restore".
2. **Fast Feedback Loop**: We want our builds and tests to run faster than a caffeinated squirrel. If you find yourself waiting, something's wrong.

## Pull Request Process

1. Ensure any install or build dependencies are removed before the end of the layer when doing a build. We don't want any sneaky slowdowns!
2. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters. Documentation is like a love letter to your future self.
3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. We use SemVer, because we're not savages.
4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you don't have permission to do that, you may request the second reviewer to merge it for you. No lone wolves here!

## Code of Conduct

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Unless you're a `Console.WriteLine` debugger. Then all bets are off. (Just kidding, we love all developers equally. Even those who think `print` statements are a valid form of logging.)

## Testing

We believe in test-driven development. In fact, we believe in it so much that we've created tools to test our tests. It's like Inception, but with unit tests.

Remember: "Program testing can be used to show the presence of bugs, but never to show their absence!" - Edsger W. Dijkstra (But we can at least make sure those bugs are fast!)

## Code Review

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.

During code review, if you see something that could be improved, don't just say "This could be faster." Instead, submit a pull request to make it faster. Be the change you want to see in the codebase.

## Documentation

Remember, code tells you how, comments tell you why. Please document your code as if the person who ends up maintaining it is a sleep-deprived developer who knows where you live. And remember, that person could be you after a long night of debugging.

## Performance

We're all about that F5 Experience, remember? If your code takes longer to run than it takes to microwave a burrito, it's probably not fast enough. Profile early, profile often. Your future self (and your future hungry self) will thank you.

## And finally...

Remember, in software development, there are only two types of projects: those that are measuring their metrics, and those that are still wondering why everything is so slow. Let's strive to be the former!

Happy coding, and may your builds be ever faster! 🚀
106 changes: 67 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,56 +1,84 @@
# Dotnet Build Metrics
# Dotnet Build and Test Metrics: Your F5 Experience, Quantified!

This is a custom MSBuild task that will measure the time to build each project and publishes the information to a datastore. The intent is to measure and improve developer experience on local workstations.
Welcome to the mono repo that's about to make your dotnet development experience smoother than a well-oiled CI/CD pipeline! We're all about measuring and improving your local dev experience, because who doesn't love a fast F5?

**_Username and hostname are collected as a part of build information_**
What is the F5 Experience? have a read [here](https://beerandserversdontmix.com/2024/08/15/an-introduction-to-the-f5-experience/)

```
{
"id": "026fe42b-7888-4a76-81ee-2ab431ae4987",
"userName": "aanand",
"cpuCount": 12,
"hostname": "25BVM13",
"platform": 2,
"os": "Microsoft Windows NT 10.0.19042.0",
"timeTaken": "453",
"branch": "master",
"type": ".Net",
"projectName": "Agoda.Cronos.Accommodation",
"repository": "[email protected]:front-end/dotnet-build-metrics.git",
"date": "2021-06-28T02:53:22.1420552Z"
}
```
## What's in the Box?

This repo is like a Swiss Army knife for .NET developers. We've got tools for:

1. Build Metrics: Measure your build times and kiss those coffee breaks goodbye!
2. Startup Metrics: Because waiting for your app to start is so last year.
3. Test Metrics: Know exactly how long your tests are taking (and why your coworker's tests are slower).

## Build and Startup Metrics: The Dynamic Duo

### Build Metrics: Time to Compile!

We've created a custom MSBuild task that measures the build time for each project and sends it off to a datastore. It's like a fitbit for your builds!

To use it, just install the [`Agoda.Builds.Metrics` NuGet package](https://www.nuget.org/packages/Agoda.Builds.Metrics) to all projects in your solution. It's easier than ordering pizza!

The task will do a HTTP POST to `http://compilation-metrics/dotnet` (or wherever you tell it to go). See exampel payload [here](examples/dotnetbuild.json).

| Parameter | Environment Variable | Default Value |
|-------------------------|---------------------------|-----------------------------------|
| Elastic Search Endpoint | BUILD_METRICS_ES_ENDPOINT | http://compilation-metrics/dotnet |

Pro tip: Set up a CNAME on your internal DNS servers for `compilation-metrics`. Your future self will thank you!

To use the task simply install the [`Agoda.Builds.Metrics` NuGet package](https://www.nuget.org/packages/Agoda.Builds.Metrics) to all of the projects in your solution, this will automatically enable metrics publication for that project.
### Agoda.DevFeedback.AspNetStartup: Because Startup Time Matters

Web API URL and the name of the endpoint are taken from environment variables if they are present as per the following table:
Why does startup time matter? read more [here](https://beerandserversdontmix.com/2024/08/15/the-f5-experience-local-setup/).

|Parameter |Environment Variable |Default Value |
|-----------------------|-------------------------|-------------------------------------|
|Elastic Search Endpoint|BUILD_METRICS_ES_ENDPOINT|http://compilation-metrics/dotnet |
This package measures your ASP.NET application's startup time in two exciting flavors:

We recommend create a CNAME on your internal DNS servers for compilation-metrics to point at an internal API that captures the data and stores it.
1. From `WebHostBuilder ConfigureServices` until `HostApplicationLifetime OnStarted` (type '.AspNetStartup')
2. From `WebHostBuilder ConfigureServices` until the first HTTP Response (type '.AspNetResponse')

To enable this magic, set these environment variables:

1. `ASPNETCORE_ENVIRONMENT` to `Development` (we promise not to slow down your production servers)
2. `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES` to include `Agoda.DevFeedback.AspNetStartup`

You can set these in your `launchSettings.json`. It's like leaving a note for your future self!

## Test Metric Collection: Because Tests Should Be Fast Too!

We've got packages for both `xUnit` and `NUnit`. They're like personal trainers for your tests!

These packages will POST their data to `http://compilation-metrics/dotnet/nunit` (or wherever `BUILD_METRICS_ES_ENDPOINT` points to). See exampel payload [here](examples/dotnettests.json).

To install, just run:

For NUnit:
```bash
dotnet package add Agoda.Tests.Metrics.NUnit
```

For xUnit:
```bash
dotnet package add Agoda.Tests.Metrics.xUnit
```

Example build log output in Visual Studio using MSBuild.
It's so easy, you might accidentally make your tests faster!

![](doc/img/VSBuildOutput.PNG)
## The F5 Experience

Example build log output in Dotnet core CLI.
Remember, we're all about that F5 Experience here. Our goal is to make your development process smoother than a freshly waxed keyboard. Here's what that means for you:

![](doc/img/DotnetCLIBuildTimeOutput.PNG)
1. **Setup Should Be a Breeze**: You should be able to clone the repo and get up and running faster than you can say "dotnet run".
2. **Fast Feedback Loop**: We want your builds, startups, and tests to run faster than a caffeinated squirrel. If you find yourself waiting, something's wrong.

## Contributing

### Agoda.DevFeedback.AspNetStartup NuGet package
We welcome contributions! Whether you're fixing bugs, improving documentation, or adding new features, we appreciate your help in making these tools even better. Check out our [Contributing Guide](CONTRIBUTING.md) for more details on how to get started.

The goal of this package is to measure the application startup time as an additional metrics that affects developer feedback besides build time.
Monoliths are especially prone to slow startup times on developer laptops and this provides visibility and tracking of improvements/regressions thereof.
Remember, in the world of Dotnet Build and Test Metrics, there are no stupid questions, only unoptimized build times!

This package measures the ASP.NET application's startup time in two ways.
1) The time from WebHostBuilder ConfigureServices until HostApplicationLifetime OnStarted sent with type '.AspNetStartup'.
2) The time from WebHostBuilder ConfigureServices until the first HTTP Reponse (measured from middleware) sent with type '.AspNetResponse'.
## And Finally...

Two environment variables are required to be set to enable the measurements.
1) `ASPNETCORE_ENVIRONMENT` needs to be set as `Development` for the functionality to be added. This is so it's only enabled locally and not on production.
2) `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES` needs to be/include `Agoda.DevFeedback.AspNetStartup`. This is for package activation due to the use of [HostingStartup](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.hostingstartupattribute?view=aspnetcore-6.0).
Remember, in software development, there are only two types of projects: those that are measuring their metrics, and those that are still wondering why everything is so slow. With these tools, you'll always know exactly where your time is going. (Spoiler alert: with our help, it won't be going to waste!)

For convenience these environment variables can be set under the lauch profile of the web application's `launchSettings.json` file and committed to the repository.
Happy coding, and may your builds be ever faster! 🚀
14 changes: 14 additions & 0 deletions examples/dotnetbuild.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"id": "026fe42b-7888-4a76-81ee-2ab431ae4987",
"userName": "aanand",
"cpuCount": 12,
"hostname": "25BVM13",
"platform": 2,
"os": "Microsoft Windows NT 10.0.19042.0",
"timeTaken": "453",
"branch": "master",
"type": ".Net",
"projectName": "Agoda.Cronos.Accommodation",
"repository": "[email protected]:front-end/dotnet-build-metrics.git",
"date": "2021-06-28T02:53:22.1420552Z"
}
47 changes: 47 additions & 0 deletions examples/dotnettests.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
{
"id": "12345",
"userName": "john.doe",
"cpuCount": 8,
"hostname": "test-server",
"platform": 1,
"os": "Windows 10",
"branch": "feature/new-test-case",
"projectName": "SampleProject",
"repository": "https://github.com/example/sample-repo",
"repositoryName": "sample-repo",
"isDebuggerAttached": true,
"nUnitTestCases": [
{
"id": "test-001",
"name": "Test_Addition",
"fullname": "SampleProject.Tests.MathTests.Test_Addition",
"methodname": "Test_Addition",
"classname": "MathTests",
"runstate": "Runnable",
"seed": 123456,
"result": "Passed",
"startTime": "2024-09-13T10:30:00Z",
"endTime": "2024-09-13T10:30:05Z",
"duration": 5.0,
"asserts": 1,
"parentId": "root-001"
},
{
"id": "test-002",
"name": "Test_Subtraction",
"fullname": "SampleProject.Tests.MathTests.Test_Subtraction",
"methodname": "Test_Subtraction",
"classname": "MathTests",
"runstate": "Ignored",
"seed": 654321,
"result": "Skipped",
"startTime": "2024-09-13T10:35:00Z",
"endTime": "2024-09-13T10:35:00Z",
"duration": 0.0,
"asserts": 0,
"parentId": "root-002"
}
],
"runId": "run-67890"
}

0 comments on commit 4050870

Please sign in to comment.