Machine name

docs/README.md

@@ -114,6 +114,7 @@
 - [Use config files only for Consul client settings and sensitive data](configuration/config-files.md)
 - [Use Consul's service discovery for server addresses](configuration/service-discovery.md)
 - [Use Consul's Key/Value store for anything else](configuration/key-value.md)
+- [Do not use MachineName](configuration/machine-name.md)
 
 ## Strings
 - [For string operations, always explicitly specify comparison/culture rules](strings/do-not-rely-on-default-rules.md)

docs/configuration/machine-name.md

@@ -0,0 +1,8 @@
+## Do not use `MachineName`
+
+
+- Use of `MachineName` tightly couples your code to the our infrastructure and its naming scheme, which can and will change over time.
+- Your code should be agnostic of environment, data center, cluster and server. Having different code paths for different environments can lead to bugs that can only be caught in production.
+- Such environmental variations are usually only required when calling external services, as you will want to call the service running in your local data center. For this, use [Consul's service discovery](service-discovery.md). It automatically supplies the correct configuration based on your environment.
+
+One exception is logging, where it can be useful to see the exact DC / cluster / server that made the request. Here, it makes sense to log the machine name.

docs/configuration/service-discovery.md

@@ -1,3 +1,3 @@
 ## Use Consul's service discovery for server addresses
 
-Server IP addresses and DNS entries should be configured using Consol's service discovery feature. Do not use the [Key/Value](key-value.md) store for this.
+Server IP addresses and DNS entries should be configured using Consul's service discovery feature. Do not use the [Key/Value](key-value.md) store for this.